> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bloom.diy/llms.txt
> Use this file to discover all available pages before exploring further.

# Best Practices

> Get the most out of Bloom with these proven strategies for building better apps, faster.

Bloom is a full-stack app builder, not a code assistant. The way you work with Bloom is different from traditional development tools. These best practices will help you build better apps with less back-and-forth.

<Note>
  For detailed prompting techniques, see the [Prompting Best Practices](/prompting-best-practices) guide, which covers the D.N.A. framework for crafting effective prompts.
</Note>

***

## Before You Start

The most successful Bloom projects start with a clear plan. Before you write your first prompt, take a few minutes to think through what you're building.

### Define your core feature

Every great app does one thing really well. Before you start building, answer these questions:

* **What's the main action?** What will users do most often in your app?
* **Who is it for?** Picture your ideal user and their situation.
* **Why will they use it?** What problem does it solve or need does it fill?

<Tip>
  Write a single sentence that captures your app's purpose. If you can't, your idea might need more focus.
</Tip>

### Start with an MVP

Resist the urge to build everything at once. Focus on 1-3 core features that prove your concept works.

<CardGroup cols={2}>
  <Card title="Good approach" icon="check">
    "Build a habit tracker where users can add habits, mark them complete, and see their streak count."
  </Card>

  <Card title="Too ambitious" icon="x">
    "Build a habit tracker with social features, gamification, AI coaching, Apple Health integration, and subscription billing."
  </Card>
</CardGroup>

You can always add features later. Getting a working app in users' hands quickly is more valuable than a feature-packed app that never ships.

### Map your user journey

Think through what happens from the moment someone opens your app:

1. What do they see first?
2. What's their first action?
3. What happens after that action?
4. How do they know it worked?

This mental walkthrough helps you describe your app to Bloom in a way that produces better results.

***

## Working with Bloom

### One change at a time

Bloom works best when each message focuses on a single thing:

* One new feature, **or**
* One improvement to existing functionality, **or**
* One bug to fix

<CardGroup cols={2}>
  <Card title="Effective" icon="check">
    "Add a delete button to each task that removes it when tapped."
  </Card>

  <Card title="Overloaded" icon="x">
    "Add delete buttons, change the font to something more modern, fix the bug where completed tasks reappear, and add a settings screen."
  </Card>
</CardGroup>

If you need multiple changes, send multiple messages. This gives Bloom the focus it needs to implement each change correctly.

### Build incrementally

The best workflow with Bloom follows a simple pattern:

<Steps>
  <Step title="Make a change" icon="wand-magic-sparkles">
    Send one focused prompt describing what you want.
  </Step>

  <Step title="Test it" icon="eye">
    Try the feature in the preview. Toggle between web and mobile views to make sure it works on both.
  </Step>

  <Step title="Iterate or move on" icon="arrows-rotate">
    If something's off, describe what you expected. If it works, move to the next feature.
  </Step>
</Steps>

Testing after each change helps you catch issues early when they're easy to fix.

### Describe behavior, not implementation

Bloom already knows the best way to build features in its stack. Your job is to describe **what should happen**, not how to make it happen.

<CardGroup cols={2}>
  <Card title="Describe behavior" icon="check">
    "When I complete a task, it should animate away and show my updated streak count."
  </Card>

  <Card title="Dictate implementation" icon="x">
    "Use React Native Reanimated with a FadeOut animation and update the streak count using a Convex mutation."
  </Card>
</CardGroup>

When you focus on behavior, Bloom can choose the optimal technical approach for your use case.

***

## Prompting Effectively

### Use the D.N.A. framework

The most effective Bloom prompts follow the D.N.A. pattern:

| Letter | Meaning             | Example                                                                |
| ------ | ------------------- | ---------------------------------------------------------------------- |
| **D**  | Describe the user   | "I'm a busy parent checking the app while cooking dinner."             |
| **N**  | Narrate the journey | "I tap a recipe, see the ingredients, and can check them off as I go." |
| **A**  | Atmosphere / vibe   | "The app should feel calm and uncluttered, not overwhelming."          |

This gives Bloom enough context to make smart decisions about touch targets, navigation, visual design, and more.

### Be specific about outcomes

Vague prompts produce vague results. Specific prompts produce exactly what you want.

<CardGroup cols={2}>
  <Card title="Specific" icon="check">
    "When I tap save, show a green checkmark animation and return to the list."
  </Card>

  <Card title="Vague" icon="x">
    "Make the save button work better."
  </Card>
</CardGroup>

### Use experiential language

Describe how features should feel, not just what they should do. Emotional adjectives help Bloom understand the experience you're after.

**Examples:**

* "The loading state should feel quick and responsive, not sluggish."
* "Deleting should feel decisive. No second-guessing."
* "The onboarding should feel welcoming and simple, not intimidating."

### Reference familiar apps

When describing complex UI patterns, reference apps your users already know. This communicates a lot of context in just a few words.

<CardGroup cols={2}>
  <Card title="Effective" icon="check">
    "The feed should scroll like Instagram stories at the top, with a vertical feed below."
  </Card>

  <Card title="Less clear" icon="x">
    "Add a horizontal scrolling section at the top with circular items, then a vertical list below."
  </Card>
</CardGroup>

Other useful references:

* "A sidebar like Notion"
* "Swipe to delete like iOS Mail"
* "A bottom sheet like Google Maps"
* "Card stacking like Tinder"

### Ask for clarification on complex features

For complex prompts, end with: *"Ask me any questions you need to fully understand what I want."*

This lets Bloom identify gaps in your description before it starts building, saving you iteration time.

***

## Iterating and Debugging

### When something doesn't work

If a feature isn't behaving correctly, give Bloom clear information:

1. **What you expected:** "When I tap the button, it should show a confirmation."
2. **What actually happened:** "Nothing happens when I tap it."
3. **Where it occurs:** "This is on the task detail screen, after I've opened a task from the list."

<CardGroup cols={2}>
  <Card title="Helpful bug report" icon="check">
    "On the profile screen, tapping 'Save Changes' doesn't update my name. I expected it to save and show a success message."
  </Card>

  <Card title="Unhelpful" icon="x">
    "Save is broken. Fix it."
  </Card>
</CardGroup>

### Include error messages

If you see an error message, include it in your prompt. Error messages contain valuable information that helps Bloom diagnose the issue.

<Tip>
  You can copy error messages directly from the [Logs](/logs) panel and paste them into your prompt.
</Tip>

### Don't guess at technical causes

You might be tempted to diagnose the problem yourself: "I think the database query is failing." Unless you're certain, stick to describing the behavior. Bloom can investigate the technical cause.

### Use screenshots to show what's wrong

Bloom has a built-in screenshot tool that captures the current state of your app. When something looks wrong or behaves unexpectedly, take a screenshot and include it in your message.

Screenshots help when:

* The layout doesn't match what you expected
* An element is in the wrong position or size
* Colors or styling look off
* You want to point to a specific part of the screen

<Tip>
  A screenshot combined with a description ("The button in this screenshot should be aligned to the right") is often more effective than words alone.
</Tip>

***

## Testing Your App

### Test on both web and mobile

If your app is meant for both platforms, test on both. The preview toolbar includes a **web/mobile toggle** that lets you switch between a browser layout and a mobile device frame. Use it after every change to catch platform-specific issues early.

<CardGroup cols={2}>
  <Card title="Web preview" icon="desktop">
    Check responsive layouts, wide-screen spacing, and hover interactions. Great for dashboards, admin tools, and content-heavy apps.
  </Card>

  <Card title="Mobile preview" icon="mobile">
    Verify touch targets, scroll behavior, and navigation. Essential for any app your users will open on their phones.
  </Card>
</CardGroup>

<Tip>
  Even if you're building primarily for one platform, a quick check on the other can reveal layout issues you wouldn't otherwise notice.
</Tip>

### Test on a real device with App Clips

The in-browser preview is great for quick checks, but testing on your actual phone reveals issues you might miss, like touch target sizes, scroll behavior, and how the app feels in your hand.

With Bloom's [**instant sharing**](/instant-sharing), you can test on a real iPhone instantly using App Clips. No TestFlight setup, no waiting for builds. Just scan the QR code and your app opens natively on your device.

<Steps>
  <Step title="Click the share button" icon="share-nodes">
    In the preview panel, click the QR code icon.
  </Step>

  <Step title="Scan with your iPhone" icon="mobile-screen">
    Point your camera at the QR code. iOS will show a notification to open the App Clip.
  </Step>

  <Step title="Test natively" icon="check">
    Your app runs with full native performance. Changes you make in Bloom appear on your phone in real time.
  </Step>
</Steps>

<Info>
  On Android, your app opens as a progressive web app in the browser. You can add it to your home screen for an app-like experience.
</Info>

### Keep your phone nearby while building

The best workflow is to keep your phone open to the app preview while you work on the web. This lets you:

* Catch mobile-specific issues immediately
* Test touch interactions as you build them
* Verify that text is readable and buttons are tappable
* See how animations feel on actual hardware

***

## Working with Data and Auth

### Let Bloom handle your database

Your app automatically includes a [Convex](https://docs.convex.dev) backend with real-time data sync, file storage, and scheduled functions. You don't need to design schemas or write database queries. Just describe what data your app needs to store.

<CardGroup cols={2}>
  <Card title="Describe the data" icon="check">
    "Users should be able to save recipes with a title, ingredients list, and photo."
  </Card>

  <Card title="Don't specify the schema" icon="x">
    "Create a recipes table with columns for id, title, ingredients as JSON, and image\_url."
  </Card>
</CardGroup>

Bloom will create the appropriate data structure and handle all the backend logic for storing, retrieving, and syncing your data in real time.

### Authentication is built in

Bloom apps come with OAuth authentication ready to use. Google sign-in is enabled by default with Bloom-managed credentials. You can also add GitHub and Apple sign-in.

When prompting for features that involve users, you don't need to specify authentication details:

<CardGroup cols={2}>
  <Card title="Focus on the feature" icon="check">
    "Only show tasks that belong to the current user."
  </Card>

  <Card title="Don't specify auth implementation" icon="x">
    "Check the user's JWT token and filter tasks by user\_id in the database query."
  </Card>
</CardGroup>

Bloom understands that "current user" means the authenticated user and will implement the correct permissions automatically.

***

## Common Pitfalls

<AccordionGroup>
  <Accordion title="Bundling unrelated changes" icon="layer-group">
    **Problem:** Asking for multiple unrelated changes in one prompt leads to confusion and partial implementations.

    **Solution:** Send separate messages for each distinct change. It feels slower but actually speeds up your overall progress.
  </Accordion>

  <Accordion title="Over-specifying technical details" icon="code">
    **Problem:** Prompts like "Create a users table with id, email, and created\_at columns" constrain Bloom unnecessarily.

    **Solution:** Describe what users should be able to do: "Users should be able to sign up with their email and see when they joined."
  </Accordion>

  <Accordion title="Vague improvement requests" icon="cloud">
    **Problem:** "Make it look better" or "improve the UX" don't give Bloom enough direction.

    **Solution:** Be specific: "Increase the spacing between cards" or "Make the primary action button more prominent."
  </Accordion>

  <Accordion title="Treating Bloom like a code editor" icon="file-code">
    **Problem:** Thinking in terms of files, functions, and code changes instead of features and experiences.

    **Solution:** Think like a product manager describing what to build, not a developer explaining how to build it.
  </Accordion>

  <Accordion title="Only testing on one platform" icon="desktop">
    **Problem:** Your app looks great on mobile but the layout breaks on web, or vice versa.

    **Solution:** Use the web/mobile toggle in the preview toolbar to check both views after each change. If your app targets both platforms, test both regularly.
  </Accordion>
</AccordionGroup>

***

## Quick Reference

<Check>
  **Before prompting**

  * Define your core feature and target user
  * Start with 1-3 features, not everything
  * Map the user journey in your head
</Check>

<Check>
  **While building**

  * One change per message
  * Test after each change
  * Describe behavior, not implementation
</Check>

<Check>
  **When prompting**

  * Use the D.N.A. framework
  * Be specific about outcomes
  * Reference familiar apps for complex UI patterns
</Check>

<Check>
  **When testing**

  * Toggle between web and mobile preview after each change
  * Use App Clips to test on your real device
  * Keep your phone preview open while working
  * Test touch interactions, not just visuals
</Check>

<Check>
  **When debugging**

  * Describe expected vs actual behavior
  * Include screenshots and error messages
  * Reference specific screens and flows
</Check>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Learn the D.N.A. Framework" icon="sparkles" href="/prompting-best-practices">
    Deep dive into prompting techniques for better results.
  </Card>

  <Card title="Start Building" icon="play" href="/building-from-web">
    Put these practices into action with your first app.
  </Card>
</CardGroup>