> ## Documentation Index
> Fetch the complete documentation index at: https://help.emergent.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# Platform Documentation
> Complete guide to building and deploying on Emergent.sh
## Understanding the Basics
### What is Preview vs Deployment?
| Feature | Preview | Deployment |
| ----------------------- | -------------------------------------------------------- | -------------------------------------------- |
| **What it is** | Your testing playground | Your live app |
| **How long it lasts** | Upto 30 minutes (if there is no interaction), then stops | Always online |
| **Resources (CPU/RAM)** | High (more powerful) | Lower (optimized) |
| **URL looks like** | yourapp.preview\.emergentagent.com | yourapp.emergent.cloud/yourapp.emergent.host |
| **Database** | Preview database | Production database |
| **Cost** | Only development credits | 50 credits (\$10) first time (starter tier) |
**Simple Rule:** Preview and deployment are completely separate. When you make changes in preview, you must redeploy to see them live.
### Machine Types in Preview (add more context - what and why does the user need to know)
| Machine | Power | When to Use |
| ----------- | -------------- | ---------------------- |
| **Regular** | Standard power | Normal development |
| **Large** | Extra power | Testing heavy features |
On paid tiers, the switch between machine types happens automatically. On basic tiers, the agent will stop and user must wake up the agent with a larger machine (simple button press)
### Before You Deploy
* Agent is awake (deployment won't work if agent is asleep)
* App works in preview (fix all errors before deploying)
* Not using too much compute (app will shut down if it uses too much) - *have to explain what is compute*
* *Optimize your queries - instruct the agent to write optimized code*
* *Plan ahead if your database will be large - reach out in advance to ensure your app is deployed smoothly.*
## Phase 1: Build Phase
### What Happens Here?
Your code gets compiled and prepared for production. Think of it like packing your app into a box ready to ship.
| **What Gets Built** | **From Where** |
| ------------------------- | ------------------------ |
| Frontend (what users see) | Your React code |
| Backend (the server) | Your Python/FastAPI code |
| JavaScript packages | package.json file |
| Python packages | requirements.txt file |
**Time:** \~5 minutes
### The Big Problem: Heavy Libraries
| **In Preview** | **In Deployment** | **The Rationale** |
| ------------------------------------------ | -------------------------------------- | --------------------------- |
| Heavy libraries work fine (high resources) | Heavy libraries fail (lower resources) | *why this is the way it is* |
| Example: Can use pandas, matplotlib | Example: These will timeout or crash | |
**Why This Happens:** Deployment has less CPU and RAM than preview. What works in testing might not work when live.\
\[\*\*Emergent allows users more freedom to create an app and then scale as you grow] \*\*
### The Solution: Use APIs Instead
| **Don't Install This** | **Do This Instead** |
| -------------------------- | --------------------------------- |
| pandas, matplotlib, plotly | Use external data analysis APIs |
| Large AI/ML libraries | Use OpenAI API, Hugging Face API |
| Playwright, Selenium | Use external automation services |
| Heavy image tools | Use Cloudinary or imgix API |
| Big calculations | Use AWS Lambda or Cloud Functions |
**Simple Rule:** If a library is large, use an API service instead of installing it - *say why.*
### Some Examples of External Services You Can Integrate With
| **Service Type** | **Some Examples** | **What It Does** | **The Reason** |
| ---------------- | ------------------------------- | -------------------------- | -------------- |
| **File Storage** | Amazon S3, Google Cloud Storage | Store images, videos, PDFs | |
| **Databases** | Supabase, PostgreSQL | Handle lots of data | |
| **File Hosting** | Cloudinary | Manage images and media | |
*What is the difference between a db and a storage service - why the investment is worth it to build serious apps.*
### Some Common Build Errors
| **Error** | **What It Means** | **How to Fix (What to tell the agent)** |
| ------------------ | --------------------------------------------- | --------------------------------------- |
| "Module not found" | Missing from package.json or requirements.txt | Add the missing package |
| "Build timeout" | App is too heavy | Remove heavy libraries, use APIs |
| "Syntax error" | Code has mistakes | Fix the code error |
| "Out of memory" | Using too much RAM | Optimize code, reduce packages |
### How to Fix Build Problems (with the agent)
Use the one-click log sharing button \_\[add GIF] \_or copy logs and share in chat
Tell the agent to optimize your code
The agent will perform the fix and solve the error
Verify everything works in preview
It is strongly recommended to ask the agent to perform a health check before attempting to deploy again. This ensures the app has a much better chance of a clean deployment.
Once solved, attempt to deploy your app again.
## Phase 2: Database Migration
### What Happens Here?
Your data moves from preview to production. Like moving your furniture to a new house.
**Time:** 1-2 minutes
### What is a Database?
| **Type** | **How It Works** | **How we handle it** |
| ------------------ | --------------------------- | ---------------------------------- |
| **Relational** | Data in tables (like Excel) | You can connect your own database. |
| **Non-Relational** | Data in flexible documents | MongoDB by default |
**Emergent uses MongoDB by default**, which is flexible and easy to work with.
### How Our Databases Work
| **What You Need to Know** | **Details** |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Shared hosting** | Multiple users share the same cluster - *simplify* |
| **Preview vs deployment** | They are completely separate databases |
| **Built-in storage** | Can store large amounts of text & limited files, images, PDFs in MongoDB - replace with a better explanation - \_why we suggest external connections. \_ |
| **Queries must be optimized** | Slow queries will fail during deployment |
**Important:** The agent cannot see your deployed database unless you share logs. Preview and deployment are separate environments.
### When Databases Get Too Heavy
| **Problem** | **Solution** |
| ------------------------- | ---------------------------------------- |
| Storing many large images | Use Amazon S3 or Google Cloud Storage |
| Lots of videos or PDFs | Use file hosting service like Cloudinary |
| Very large datasets | Use Supabase or PostgreSQL |
| High traffic app | Get dedicated database (contact support) |
### Making Queries Optimized
| **Query Speed** | **Result** | **What to Do** |
| ----------------------- | ----------------------------------- | --------------------- |
| **Unoptimized queries** | Deployment may fail, or timeout | Ask agent to optimize |
| **Optimized queries** | Deployment has improved performance | Ready to go |
**How to Optimize:** Tell the agent "optimize my database queries" and it will rewrite them better.
### Common Database Errors (shows up in logs, share with agent to fix)
| **Error** | **What It Means** | **How to Fix (Ask the agent)** | **Simple Fix** |
| ------------------- | ------------------------- | ------------------------------ | --------------------------- |
| "Connection failed" | Can't connect to database | Check MONGO\_URL in .env file | Fork and Replace deployment |
| "Query timeout" | Query too slow | Ask agent to optimize queries | |
| "Schema error" | Data format is wrong | Ask agent to fix | |
### Connecting Your Own Database
Get URL and password from your database provider
Provide credentials to the Emergent agent
Agent sets up the connection
Verify it works in preview
Deploy with your custom database
## Phase 3: Exporting Secrets
### What Are Secrets?
Secrets are passwords, API keys, and settings your app needs. They go in the .env file.
**Time:** 1-2 minutes
### Two Types of Secrets
| **Type** | **Examples** | **Who Provides** |
| ---------------------- | ---------------------------------------------------- | ---------------- |
| **Emergent gives you** | MongoDB URL, Backend URL, Port, CORS | Automatic |
| **You provide** | API keys, your database passwords, external services | You |
### The Golden Rules
Anyone can see them (security risk)
Easy to change, stays private
One wrong character breaks everything
Changes only work after you redeploy
### What Breaks Your App
| **If This is Wrong** | **This Happens** |
| -------------------- | ---------------------------- |
| Port number | App can't connect |
| URL | You get 404 errors |
| API key | External services don't work |
| Database URL | Can't load any data |
**Be careful!** Double-check everything before deploying.
### Common Secret Errors
| **Error** | **What It Means** | **How to Fix** |
| -------------------- | ---------------------------- | -------------------------- |
| "Missing variable" | You forgot to add it to .env | Add the missing variable |
| "Invalid API key" | Key is wrong or expired | Get a new valid key |
| "Connection refused" | URL or port is wrong | Fix the URL or port number |
### Best Practices
Make sure they work by testing them in preview first
Save a copy in case you need to restore settings
Use descriptive names so you know what each does
External services need to know your new domain
## Phase 4: Deploy and Health Check
### Deploy: Setting Up Infrastructure
Your app is launched on servers and made available to the world.
**What Happens:**
* Servers are set up (Kubernetes)
* Your app is installed on servers
* Network connections are configured
* Resources (CPU/RAM) are assigned
**Time:** 3-5 minutes
### Common Deploy Errors
| **Error** | **What It Means** | **How to Fix** |
| --------------------- | ------------------------ | ------------------------------------------------------- |
| "Provisioning failed" | Server setup problem | Wait and try again, contact support if it keeps failing |
| "Container crashed" | App won't start | Check logs, fix startup code |
| "Port conflict" | Port already being used | Check port settings |
| "Out of resources" | App needs too much power | Optimize app, use external APIs |
### Health Check: Is Everything Working?
After deployment, the system checks if your app is actually working.
**What Gets Checked:**
* App responds to requests
* APIs are working
* Frontend loads correctly
* Database is connected
* All services are running
**Time:** 1-2 minutes
### If Health Check Fails
| **Problem** | **What It Means** | **How to Fix** |
| ----------------- | ------------------------- | -------------------------- |
| "App crashed" | Code error on startup | Review logs, fix the error |
| "API error 500" | Backend has problems | Check backend code |
| "White screen" | Frontend won't load | Check frontend build |
| "Database failed" | Can't connect to database | Verify connection info |
| "CORS error" | Security settings wrong | Fix CORS configuration |
**Important:** If health check fails, your app won't go live. This protects you from publishing a broken app.
### Total Deployment Time
| **All Phases Combined** | **Typical Time** |
| -------------------------------------------------- | ---------------- |
| Build + Database + Secrets + Deploy + Health Check | 10-15 minutes |
## Understanding Deployment Costs
### How Much Does It Cost?
| **What** | **Cost** | **When You Pay** |
| ------------------------------ | ----------------- | ---------------------- |
| **First time you deploy** | 50 credits (\$10) | Once per app |
| **Update same app (redeploy)** | FREE | Every time after first |
| **Deploy a new app** | 50 credits (\$10) | Once per new app |
### What Do You Get for 50 Credits?
Your app runs always online
Managed MongoDB included
All deployment steps included
Auto-linking for your domains
**Good News:** After paying once, you can update your app unlimited times for free.
### What Happens When You Redeploy?
| This Updates | This Stays the Same |
| -------------------------------- | ------------------------------------- |
| Your code (frontend and backend) | Your database (from first deployment) |
**Important:** Redeploying updates your code but NOT your database.
If you changed data in preview after your first deployment, that data won't appear in production. You need to manually move it.
## Replacing Existing Deployments
### Why Replace Instead of Deploy New?
**Scenario:** You forked your app, made it better, and want the new version to replace the old one WITHOUT paying another 50 credits.
### Your Options
| **Option** | **When to Use** | **What Happens to Data** |
| ----------------- | ------------------------------ | ----------------------------- |
| **Fresh start** | No important data to keep | Old data deleted, start fresh |
| **Keep old data** | Users have important data | Old data stays |
| **Merge data** | Want old AND new data together | Combines both databases |
### Option 1: Fresh Start (Copies Preview Data)
Click "Replace Existing Deployment"
Select "Fresh Database" option
New app replaces old one
**Result:** Old app gone, new app live, no extra charge.
### Option 2: Merge Old and New Data
Email [support@emergent.sh](mailto:support@emergent.sh) to export data (up to 24 hours)
Get your data when ready (few minutes)
Give data to agent, ask to merge
Tell agent to verify no data conflicts
Deploy with combined database
**Result:** All data preserved, no extra charge.
### Option 3: Zero Risk Method (High Traffic Apps)
Request from support (time only)
Deploy as standalone (50 credits)
Load exported data to new app
Check all data and features work
Shut down old app (free)
**Result:** Zero downtime, zero data loss, but costs 50 credits.
## Working with URLs and Domains
### The Three Types of URLs
| **URL Type** | **Looks Like** | **When It's Online** | **Power** |
| --------------- | ------------------------------ | -------------------- | --------- |
| **Preview** | app.preview\.emergentagent.com | 30 minutes only | High |
| **Deployed** | app.emergent.host | Always | Normal |
| **Your domain** | yourdomain.com | Always | Normal |
### Adding Your Own Domain
Purchase from GoDaddy, Namecheap, etc (right away)
Update at your domain provider (right away)
Use Emergent dashboard (5-10 minutes)
DNS spreads worldwide automatically (10 min to 2 hours)
**After You Link Domain:** Update all external services (APIs, payment processors, OAuth) to use your new domain instead of the old emergent.host URL.
## Troubleshooting Guide
### Quick Problem Solver
| **Problem** | **Quick Fix** |
| ----------------------- | ------------------------------------------------- |
| **Build fails** | Share logs with agent, check for missing packages |
| **Database fails** | Check MONGO\_URL, ask agent to optimize queries |
| **Deploy fails** | Check logs, contact support if it keeps happening |
| **App won't start** | Check .env file for wrong values |
| **Domain doesn't work** | Wait 10 min to 2 hours for DNS to update |
| **APIs stop working** | Update URLs at external service providers |
| **Preview shuts down** | Use Large machine or make app lighter |
| **Can't deploy** | Wake up the agent first |
### When to Share Logs
| **Problem** | **What Logs Show** |
| -------------- | ------------------------------------ |
| Build fails | What packages are missing |
| Database fails | What queries are slow |
| Deploy fails | What infrastructure problem occurred |
| App crashes | What code error happened |
**How:** Click the one-click log share button, send to agent, agent tells you how to fix.
### When to Email Support
Email [**support@emergent.sh**](mailto:support@emergent.sh) when:
| **Problem** | **What to Include** |
| ---------------------------- | -------------------------------- |
| Same error keeps happening | Job ID, logs, what you tried |
| Server/infrastructure issues | Job ID, error message |
| Need to export database | Job ID, how big your database is |
| Want dedicated database | How much traffic you have |
| Domain problems | Your domain name, DNS settings |
## Pre-Deployment Checklist
* Works perfectly in preview (catch problems early)
* Database queries are fast (prevent timeouts)
* Using APIs instead of heavy libraries (avoid crashes)
* All packages listed in config files (prevent build errors)
* API keys work (make sure integrations function)
* Secrets in .env file, not code (security)
* Agent is awake (can't deploy if agent is asleep)
## Quick Reference
### Key Terms Simple Guide
| **Term** | **What It Means** |
| ----------------- | --------------------------------------------------------- |
| **Preview** | Testing area, stops after 30 min, high power |
| **Deployment** | Live app, always on, normal power |
| **Redeploy** | Update your code for free (same app) |
| **Job ID** | Your app's unique number |
| **Heavy library** | Big package that works in preview but fails when deployed |
| **External API** | Service you connect to instead of installing locally |
| **.env file** | Where you store passwords and keys |
| **Agent** | AI helper that builds and fixes your app |