deno-deploy

What this skill does

# Deno Deploy

This skill provides guidance for deploying applications to Deno Deploy.

## Scope Boundaries

This skill applies **only** to Deno Deploy questions. Follow these rules:

- If the user asks about **AWS Lambda, Vercel, Netlify, Google Cloud Run, Docker, Kubernetes, or any other deployment platform**, answer using that platform directly. Do not mention Deno Deploy at all — not as an alternative, not as a comparison, not as a suggestion.
- If the user asks about **running a local Deno script** (not deploying), answer the local question directly. Do not mention Deno Deploy, deployment, or the `--tunnel` flag.
- Do not include `deno deploy` commands, Deno KV, or Deno Deploy environment variable configuration in responses about other platforms or local-only scripts.
- Only discuss Deno Deploy when the user explicitly asks about Deno Deploy or deploying a Deno application to production.

## Important: Use `deno deploy`, NOT `deployctl`

**Always use the `deno deploy` command.** Do NOT use `deployctl`.

- `deployctl` is for Deno Deploy Classic (deprecated)
- `deno deploy` is the modern, integrated command built into the Deno CLI
- **Requires Deno >= 2.4.2** - the `deno deploy` subcommand was introduced in Deno 2.4

## When Unsure About CLI Flags

**Always run `--help` before guessing at flags.** The `deno deploy` subcommand has many flags, and they change between versions. When you're unsure what a command accepts:

```bash
# See all subcommands
deno deploy --help

# See flags for a specific subcommand
deno deploy create --help
deno deploy env --help
deno deploy database --help
```

This takes seconds and prevents repeated trial-and-error failures. Never assume a flag exists — check first.

## Deployment Workflow

**Always show the core deploy command first** — then explain diagnostic steps. When a user asks "how do I deploy?", lead with the actual command (`deno deploy --prod`) before covering pre-flight checks and configuration.

### Step 1: Locate the App Directory

Before running any deploy commands, find where the Deno app is located:

```bash
# Check if deno.json exists in current directory
if [ -f "deno.json" ] || [ -f "deno.jsonc" ]; then
  echo "APP_DIR: $(pwd)"
else
  # Look for deno.json in immediate subdirectories
  find . -maxdepth 2 -name "deno.json" -o -name "deno.jsonc" 2>/dev/null | head -5
fi
```

All deploy commands must run from the app directory.

### Step 2: Pre-Flight Checks

Check Deno version and existing configuration:

```bash
# Check Deno version (must be >= 2.4.2)
deno --version | head -1

# Check for existing deploy config
grep -E '"org"|"app"' deno.json deno.jsonc 2>/dev/null || echo "NO_DEPLOY_CONFIG"
```

### Step 3: Check for Startup Dependencies

Before deploying, check if the app connects to a database or external service at startup (e.g., top-level `await initDb()` in `main.ts`). If it does, the deploy will fail during warmup because the database doesn't exist yet.

**If the app has startup database dependencies, follow this order:**

1. **Create the app with `--no-wait`** so a warmup failure doesn't block you:
   ```bash
   deno deploy create \
     --org <ORG_NAME> --app <APP_NAME> \
     --source local --runtime-mode dynamic --entrypoint main.ts \
     --build-timeout 5 --build-memory-limit 1024 --region us \
     --no-wait
   ```

2. **Provision and assign the database:**
   ```bash
   deno deploy database provision my-db --kind prisma --region us-east-1
   deno deploy database assign my-db --app <APP_NAME>
   ```

3. **Redeploy** (now the database exists, warmup will succeed):
   ```bash
   deno deploy --prod
   ```

If the app has no startup dependencies, skip this step and deploy normally below.

### Step 4: Deploy Based on Configuration

**If `deploy.org` AND `deploy.app` exist in deno.json:**
```bash
# Build if needed (Fresh, Astro, etc.)
deno task build

# Deploy to production
deno deploy --prod
```

**If NO deploy config exists:**

**Apps must be created before they can be deployed to.** You cannot run `deno deploy --prod` until an app exists.

**IMPORTANT: Ask the user first** - Do they have an existing app on Deno Deploy, or do they need to create a new one?

**If they have an existing app**, add the config directly to deno.json:
```json
{
  "deploy": {
    "org": "<ORG_NAME>",
    "app": "<APP_NAME>"
  }
}
```
The org name is in the Deno Deploy console URL (e.g., `console.deno.com/your-org-name`). Once this config is in place, subsequent deploys just need `deno deploy --prod`.

**If they need to create a new app:**

The CLI needs an organization name. Find it at https://console.deno.com - the org is in the URL path (e.g., `console.deno.com/your-org-name`).

**Interactive creation** (opens a browser — only works when a human is at the keyboard):
```bash
deno deploy create --org <ORG_NAME>
# A browser window opens - complete the app creation there
```

**Non-interactive creation** (use when an AI agent is performing the deploy, or in CI/CD):
```bash
deno deploy create \
  --org <ORG_NAME> \
  --app <APP_NAME> \
  --source local \
  --runtime-mode dynamic \
  --entrypoint main.ts \
  --build-timeout 5 \
  --build-memory-limit 1024 \
  --region us
```

The create command also does the initial deploy. After it completes, `deno.json` is updated with `deploy.org` and `deploy.app` automatically. From that point on, subsequent deploys only need:
```bash
deno deploy --prod
```

After completion, verify the config was saved:
```bash
grep -E '"org"|"app"' deno.json
```

**When an AI agent is performing the deployment**, always use the non-interactive flow with explicit flags. The interactive flow requires browser windows and terminal prompts that agents cannot navigate.

## Core Commands

### Production Deployment

```bash
deno deploy --prod
```

### Preview Deployment

```bash
deno deploy
```

Preview deployments create a unique URL for testing without affecting production.

### Targeting Specific Apps

```bash
deno deploy --org my-org --app my-app --prod
```

### Configuring an Entrypoint

Set the entrypoint in your `deno.json` (this is used by `deno deploy create` during app creation):

```json
{
  "deploy": {
    "entrypoint": "main.ts"
  }
}
```

Note: `--entrypoint` is a flag on `deno deploy create`, not on `deno deploy` itself.

### Additional Flags

These flags are available on `deno deploy create` (and apply during the initial deploy):

| Flag | Purpose |
|------|---------|
| `--allow-node-modules` | Include node_modules directory in upload |
| `--no-wait` | Skip waiting for the build to complete |

## Creating Apps (Non-Interactive Reference)

When any flag beyond `--org` is provided, `deno deploy create` runs in non-interactive mode — all required flags must be specified. This is the recommended approach for AI agents and CI/CD pipelines.

### Required Flags

| Flag | Description |
|------|-------------|
| `--org <name>` | Organization name |
| `--app <name>` | Application name (becomes your URL: `<app>.deno.dev`) |
| `--source <local\|github>` | Deploy from local files or a GitHub repo |
| `--build-timeout <minutes>` | Build timeout: 5, 10, 15, 20, 25, or 30 |
| `--build-memory-limit <MB>` | Memory limit: 1024, 2048, 3072, or 4096 |
| `--region <region>` | Deployment region: us, eu, or global |

### GitHub Source Flags

When using `--source github`, you also need:

| Flag | Description |
|------|-------------|
| `--owner <name>` | GitHub repository owner |
| `--repo <name>` | GitHub repository name |

### Build Configuration Flags

| Flag | Description |
|------|-------------|
| `--app-directory <path>` | Path to app directory (for monorepos) |
| `--framework-preset <preset>` | Framework preset (see [Frameworks](references/FRAMEWORKS.md)) |
| `--install-command <cmd>` | Custom install command |
| `--build-command <cmd>` | Custom build command |
| `--pre-deploy-command <cmd>` | Command to run before deploy |
| `--do-not-use-detected-build-config` | Skip auto-detection of framework config |

Th