insforge-cli/references/deployments/deploy.md

npx -y @insforge/cli deployments deploy — frontend hosting (Vercel)

Deploy a frontend project (static site / SPA / Next.js / etc.) to InsForge hosting (via Vercel) from its source directory.

Looking to deploy a backend Docker container (API, worker)? Use npx -y @insforge/cli compute deploy instead — see compute-deploy.md.

Syntax

npx -y @insforge/cli deployments deploy [source-directory] [options]

Options

Option	Description
--env <vars>	Environment variables as JSON: '{"KEY":"value"}'
--meta <meta>	Metadata as JSON

Default Directory

Current directory (.) if not specified. In most projects, this should be the app root, not dist/, build/, or .next/.

What It Does

1. Creates a deployment record (gets presigned upload URL)
2. Zips the source directory (max compression)
3. Uploads the zip to the presigned URL
4. Starts the deployment with env vars and metadata
5. Polls status every 5 seconds for up to 2 minutes
6. Returns the live URL and deployment ID

Excluded Files

The following are automatically excluded from the upload:

• node_modules/, .git/, .next/, dist/, build/
• .env*, .DS_Store, .insforge/, *.log

Because build output is excluded automatically, deploy the project source tree/root directory instead of pointing the command at dist/, build/, or .next/.

Custom excludes with .vercelignore

To exclude additional files, add a .vercelignore file to the deploy source directory. It uses .gitignore syntax, including ! negation:

# .vercelignore
*.md
drafts/
!IMPORTANT.md

Notes:

• Patterns apply on top of the built-in excludes above; the built-ins always stay excluded and cannot be re-included with !.
• The .vercelignore file itself is never uploaded.
• If the project was previously deployed directly with the Vercel CLI, an existing .vercelignore is honored as-is.

Environment Variables Are Required

Frontend apps need env vars (API URL, anon key, etc.) to connect to InsForge. Deploying without them produces a broken app. There are two ways to provide them:

Option A — Persistent env vars (recommended for repeated deploys):

# Check what's already configured
npx -y @insforge/cli deployments env list

# Set env vars — these persist across all future deployments
npx -y @insforge/cli deployments env set VITE_INSFORGE_URL https://my-app.us-east.insforge.app
npx -y @insforge/cli deployments env set VITE_INSFORGE_ANON_KEY ik_xxx

# Deploy the project source — persistent vars are applied automatically
npx -y @insforge/cli deployments deploy .

Option B — Inline --env flag (one-off or override):

npx -y @insforge/cli deployments deploy . --env '{"VITE_INSFORGE_URL": "https://my-app.us-east.insforge.app", "VITE_INSFORGE_ANON_KEY": "ik_xxx"}'

Before deploying, always confirm env vars are in place: either check deployments env list shows the required vars, or pass --env on the command.

Examples

# Deploy with persistent env vars already set
npx -y @insforge/cli deployments deploy .

# Deploy with inline env vars
npx -y @insforge/cli deployments deploy . --env '{"VITE_API_URL": "https://my-app.us-east.insforge.app", "VITE_ANON_KEY": "ik_xxx"}'

# JSON output
npx -y @insforge/cli deployments deploy . --json

Typical Workflow

Pre-Deployment: Local Build Verification

CRITICAL: Always verify local build succeeds before deploying to InsForge.

Local builds are faster to debug and don't waste server resources on avoidable errors.

After the build passes locally, deploy the project source directory (usually .). Do not deploy the generated output folder; the CLI excludes it automatically.

Local Build Checklist:

# 1. Install dependencies
npm install

# 2. Create production environment file
# Use the correct prefix for your framework:
# - Vite: VITE_INSFORGE_URL
# - Next.js: NEXT_PUBLIC_INSFORGE_URL
# - CRA: REACT_APP_INSFORGE_URL
# - Astro: PUBLIC_INSFORGE_URL
cat > .env.production << 'EOF'
INSFORGE_URL=https://your-project.insforge.app
INSFORGE_ANON_KEY=your-anon-key
EOF

# 3. Run production build
npm run build

Common Build Errors & Solutions

Error	Cause	Solution
Missing env var errors	Build-time env vars not set	Create .env.production with framework-specific prefix
Module resolution errors	Edge functions scanned by compiler	Exclude edge function directories from build config
Static export conflicts	Dynamic routes with static export	Use SSR or configure static params per framework docs
module_not_found	Missing dependency	Run npm install and verify package.json

Framework-Specific Notes

Environment Variables by Framework:

Framework	Prefix	Example
Vite	VITE_	VITE_INSFORGE_URL
Next.js	NEXT_PUBLIC_	NEXT_PUBLIC_INSFORGE_URL
Create React App	REACT_APP_	REACT_APP_INSFORGE_URL
Astro	PUBLIC_	PUBLIC_INSFORGE_URL
SvelteKit	PUBLIC_	PUBLIC_INSFORGE_URL

Edge Functions: If your project has edge functions in a separate directory (commonly functions/ for Deno-based functions), exclude them from your frontend build to prevent module resolution errors. Add the directory to your TypeScript or bundler exclude configuration.

Start to Deploy

# 4. Ensure env vars are set (check existing, add any missing)
npx -y @insforge/cli deployments env list
npx -y @insforge/cli deployments env set VITE_INSFORGE_URL https://my-app.us-east.insforge.app
npx -y @insforge/cli deployments env set VITE_INSFORGE_ANON_KEY ik_xxx

# 5. Deploy the project source (persistent env vars are applied automatically)
npx -y @insforge/cli deployments deploy .

Alternatively, pass env vars inline: npx -y @insforge/cli deployments deploy . --env '{"VITE_INSFORGE_URL": "...", "VITE_INSFORGE_ANON_KEY": "..."}'

Check Deployment Status

Wait 30 seconds to 1 minute, then check status with npx -y @insforge/cli deployments status <id>.

Status Values

Status	Description
WAITING	Waiting for source upload
UPLOADING	Uploading to build server
QUEUED	Queued for build
BUILDING	Building (typically ~1 min)
READY	Complete - URL available
ERROR	Build or deployment failed
CANCELED	Deployment cancelled

SPA Routing

For React single-page apps, ensure a vercel.json exists in the project root:

{
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/index.html"
    }
  ]
}

Best Practices

1. Deploy the project source directory

   • Run the command from your app root, or pass that directory explicitly
   • Do not deploy dist/, build/, or .next/ directly; the CLI excludes them automatically
   • Never include node_modules, .git, .env, or .insforge in the upload
   • Large assets should go to InsForge Storage, not the deployment

2. Always set env vars before deploying

   • Use deployments env set for persistent vars, or --env for one-off deploys
   • Run deployments env list to verify vars are in place before deploying
   • Never commit .env files to source or include in zip
   • Use the correct env var prefix for your framework: VITE_*, NEXT_PUBLIC_*, REACT_APP_*, etc.

3. Always build locally first to catch errors before deploying.

4. Include vercel.json for SPAs

   • Required for client-side routing to work properly

Common Mistakes

Mistake	Solution
Including node_modules in zip	Exclude it - will be installed during build
Including .env files	Use deployments env set or --env flag instead
Deploying dist/, build/, or .next/ directly	Deploy the project source/root directory instead; the CLI excludes build output automatically
Deploying without env vars	Run deployments env list first — if empty, set vars with deployments env set or --env
Missing VITE_* env vars	Add all required build-time variables with correct framework prefix
Checking status too early	Wait 30sec-1min before checking status
Missing vercel.json for SPA	Add rewrites config for client-side routing