From 565252d9219d9a5208af2c0ef1f9e2469fa76c55 Mon Sep 17 00:00:00 2001 From: Minsu Lee Date: Tue, 15 Sep 2026 21:06:46 +0900 Subject: [PATCH 1/3] feat(deno): add deno plugin bundling official denoland/skills Bundle the 5 official skills from github.com/denoland/skills (MIT, maintained by Deno Land) via skills.sh with a pinned skills-lock.json, so the existing weekly update-skills workflow tracks upstream. Registered in the Claude, Codex, and Cursor marketplaces and in release-please. --- .agents/plugins/marketplace.json | 12 + .claude-plugin/marketplace.json | 15 + .cursor-plugin/marketplace.json | 5 + .release-please-manifest.json | 3 +- README.md | 7 + .../deno/.agents/skills/deno-deploy/SKILL.md | 636 ++++++++++++++++++ .../deno-deploy/references/AUTHENTICATION.md | 185 +++++ .../deno-deploy/references/DATABASES.md | 159 +++++ .../skills/deno-deploy/references/DENO_KV.md | 153 +++++ .../skills/deno-deploy/references/DOMAINS.md | 93 +++ .../deno-deploy/references/FRAMEWORKS.md | 215 ++++++ .../deno-deploy/references/ORGANIZATIONS.md | 86 +++ .../skills/deno-deploy/references/RUNTIME.md | 103 +++ .../deno-deploy/references/TROUBLESHOOTING.md | 191 ++++++ .../.agents/skills/deno-frontend/SKILL.md | 86 +++ .../skills/deno-frontend/references/FRESH.md | 286 ++++++++ .../references/FRESH_MIGRATION.md | 70 ++ .../deno/.agents/skills/deno-sandbox/SKILL.md | 412 ++++++++++++ plugins/deno/.agents/skills/deno/SKILL.md | 281 ++++++++ .../.agents/skills/deno/references/CLI.md | 197 ++++++ .../.agents/skills/migrate-to-deno/SKILL.md | 168 +++++ .../migrate-to-deno/references/FROM_BUN.md | 136 ++++ .../migrate-to-deno/references/FROM_NPM.md | 68 ++ .../migrate-to-deno/references/FROM_PNPM.md | 70 ++ .../migrate-to-deno/references/FROM_YARN.md | 69 ++ .../migrate-to-deno/references/NODE_APIS.md | 110 +++ plugins/deno/.claude-plugin/plugin.json | 23 + plugins/deno/.codex-plugin/plugin.json | 36 + plugins/deno/.cursor-plugin/plugin.json | 27 + plugins/deno/README.md | 83 +++ plugins/deno/plugin.json | 23 + plugins/deno/skills-lock.json | 35 + release-please-config.json | 26 + 33 files changed, 4068 insertions(+), 1 deletion(-) create mode 100644 plugins/deno/.agents/skills/deno-deploy/SKILL.md create mode 100644 plugins/deno/.agents/skills/deno-deploy/references/AUTHENTICATION.md create mode 100644 plugins/deno/.agents/skills/deno-deploy/references/DATABASES.md create mode 100644 plugins/deno/.agents/skills/deno-deploy/references/DENO_KV.md create mode 100644 plugins/deno/.agents/skills/deno-deploy/references/DOMAINS.md create mode 100644 plugins/deno/.agents/skills/deno-deploy/references/FRAMEWORKS.md create mode 100644 plugins/deno/.agents/skills/deno-deploy/references/ORGANIZATIONS.md create mode 100644 plugins/deno/.agents/skills/deno-deploy/references/RUNTIME.md create mode 100644 plugins/deno/.agents/skills/deno-deploy/references/TROUBLESHOOTING.md create mode 100644 plugins/deno/.agents/skills/deno-frontend/SKILL.md create mode 100644 plugins/deno/.agents/skills/deno-frontend/references/FRESH.md create mode 100644 plugins/deno/.agents/skills/deno-frontend/references/FRESH_MIGRATION.md create mode 100644 plugins/deno/.agents/skills/deno-sandbox/SKILL.md create mode 100644 plugins/deno/.agents/skills/deno/SKILL.md create mode 100644 plugins/deno/.agents/skills/deno/references/CLI.md create mode 100644 plugins/deno/.agents/skills/migrate-to-deno/SKILL.md create mode 100644 plugins/deno/.agents/skills/migrate-to-deno/references/FROM_BUN.md create mode 100644 plugins/deno/.agents/skills/migrate-to-deno/references/FROM_NPM.md create mode 100644 plugins/deno/.agents/skills/migrate-to-deno/references/FROM_PNPM.md create mode 100644 plugins/deno/.agents/skills/migrate-to-deno/references/FROM_YARN.md create mode 100644 plugins/deno/.agents/skills/migrate-to-deno/references/NODE_APIS.md create mode 100644 plugins/deno/.claude-plugin/plugin.json create mode 100644 plugins/deno/.codex-plugin/plugin.json create mode 100644 plugins/deno/.cursor-plugin/plugin.json create mode 100644 plugins/deno/README.md create mode 100644 plugins/deno/plugin.json create mode 100644 plugins/deno/skills-lock.json diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index 7fadec61..44f25efa 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -956,6 +956,18 @@ }, "category": "Development" }, + { + "name": "deno", + "source": { + "source": "local", + "path": "./plugins/deno" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Development" + }, { "name": "modern-web-guidance", "source": { diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 77b0165f..4794cc2c 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1319,6 +1319,21 @@ } } }, + { + "name": "deno", + "description": "Official Deno skills - dependency management with npm and JSR, permissions, the built-in toolchain, migrating from Node/npm/yarn/pnpm/bun, Fresh, and Deno Deploy", + "category": "development", + "keywords": ["deno", "runtime", "typescript", "javascript", "jsr", "permissions", "test-runner"], + "tags": ["runtime", "tooling"], + "source": "./plugins/deno", + "relevance": { + "topic": "Deno", + "signals": { + "cli": ["deno"], + "filesRead": ["**/deno.json", "**/deno.jsonc", "**/deno.lock"] + } + } + }, { "name": "modern-web-guidance", "description": "Keep your coding agent up to date with the latest web best practices from the Google Chrome team", diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json index ff31f0a7..afa17627 100644 --- a/.cursor-plugin/marketplace.json +++ b/.cursor-plugin/marketplace.json @@ -309,6 +309,11 @@ "source": "./plugins/bun", "description": "All-in-one JavaScript/TypeScript toolkit: fast runtime, package manager, test runner, and bundler - version-aware skill backed by the ask CLI" }, + { + "name": "deno", + "source": "./plugins/deno", + "description": "Official Deno skills - dependency management with npm and JSR, permissions, the built-in toolchain, migrating from Node/npm/yarn/pnpm/bun, Fresh, and Deno Deploy" + }, { "name": "java-development", "source": "./plugins/java-development", diff --git a/.release-please-manifest.json b/.release-please-manifest.json index eb994527..82e0a25d 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -68,5 +68,6 @@ "plugins/playwright-cli": "1.0.0", "plugins/greptile": "1.1.1", "plugins/shadcn-ui": "1.1.0", - "plugins/tanstack": "0.2.0" + "plugins/tanstack": "0.2.0", + "plugins/deno": "1.0.0" } diff --git a/README.md b/README.md index 895ad07b..9389bac3 100644 --- a/README.md +++ b/README.md @@ -366,6 +366,12 @@ Version-aware skill for the Bun JavaScript/TypeScript toolkit — runtime, packa **Install:** `/plugin install bun@pleaseai` | **Source:** [plugins/bun](https://github.com/pleaseai/claude-code-plugins/tree/main/plugins/bun) +#### Deno + +Official [Deno skills](https://github.com/denoland/skills) — dependency management with npm and JSR, permissions, `deno.json`, the built-in toolchain, migrating from Node/npm/yarn/pnpm/bun, Fresh, and Deno Deploy. + +**Install:** `/plugin install deno@pleaseai` | **Source:** [plugins/deno](https://github.com/pleaseai/claude-code-plugins/tree/main/plugins/deno) + #### Graphite [![tessl](https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.tessl.io%2Fv1%2Fbadges%2Fpleaseai%2Fgraphite)](https://tessl.io/registry/pleaseai/graphite) @@ -621,6 +627,7 @@ Once the marketplace is added (or files copied), the following plugins are avail /plugin install portless@pleaseai /plugin install zod@pleaseai /plugin install bun@pleaseai +/plugin install deno@pleaseai /plugin install graphite@pleaseai /plugin install claude-md-management@pleaseai /plugin install fetch@pleaseai diff --git a/plugins/deno/.agents/skills/deno-deploy/SKILL.md b/plugins/deno/.agents/skills/deno-deploy/SKILL.md new file mode 100644 index 00000000..f25bf4af --- /dev/null +++ b/plugins/deno/.agents/skills/deno-deploy/SKILL.md @@ -0,0 +1,636 @@ +--- +name: deno-deploy +description: Use when deploying Deno apps to production, asking about Deno Deploy, or working with `deno deploy` CLI commands. Covers deployment workflows, environment variables, KV database access, custom domains, the --tunnel flag for local development, and the `deno deploy` command reference. +license: MIT +metadata: + author: denoland + version: "1.5" +--- + +# 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 --app \ + --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 + ``` + +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": "", + "app": "" + } +} +``` + +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 +# 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 \ + --app \ + --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 ` | Organization name | +| `--app ` | Application name (becomes your URL: `.deno.dev`) | +| `--source ` | Deploy from local files or a GitHub repo | +| `--build-timeout ` | Build timeout: 5, 10, 15, 20, 25, or 30 | +| `--build-memory-limit ` | Memory limit: 1024, 2048, 3072, or 4096 | +| `--region ` | Deployment region: us, eu, or global | + +### GitHub Source Flags + +When using `--source github`, you also need: + +| Flag | Description | +| ---------------- | ----------------------- | +| `--owner ` | GitHub repository owner | +| `--repo ` | GitHub repository name | + +### Build Configuration Flags + +| Flag | Description | +| ------------------------------------ | ------------------------------------------------------------- | +| `--app-directory ` | Path to app directory (for monorepos) | +| `--framework-preset ` | Framework preset (see [Frameworks](references/FRAMEWORKS.md)) | +| `--install-command ` | Custom install command | +| `--build-command ` | Custom build command | +| `--pre-deploy-command ` | Command to run before deploy | +| `--do-not-use-detected-build-config` | Skip auto-detection of framework config | + +The CLI auto-detects your framework and build configuration. If a framework is +detected, you can skip `--install-command`, `--build-command`, +`--pre-deploy-command`, and `--runtime-mode` — they'll be inferred from the +preset. Use `--do-not-use-detected-build-config` to override detection. **When +using this flag, all three build commands (`--install-command`, +`--build-command`, `--pre-deploy-command`) plus `--runtime-mode` become +required** — omitting any of them causes exit code 2. + +### Runtime Mode Flags + +You must pick a runtime mode with `--runtime-mode ` (unless a +framework preset handles it). + +**Dynamic mode** (for apps with a server): + +| Flag | Description | +| --------------------------- | ------------------------------------------- | +| `--entrypoint ` | Entry file (required for dynamic mode) | +| `--arguments ` | Arguments passed to entrypoint (repeatable) | +| `--working-directory ` | Working directory for the process | + +**Static mode** (for static sites): + +| Flag | Description | +| -------------------- | --------------------------------------------------- | +| `--static-dir ` | Directory to serve static files from (required) | +| `--single-page-app` | Serve index.html for routes that don't match a file | + +### Other Flags + +| Flag | Description | +| ---------------------- | ----------------------------------------------------- | +| `--dry-run` | Validate everything without actually creating the app | +| `--no-wait` | Don't wait for the build to complete | +| `--allow-node-modules` | Include node_modules in the upload | + +### Examples + +**Simple Deno server:** + +```bash +deno deploy create \ + --org my-org --app my-api \ + --source local \ + --runtime-mode dynamic --entrypoint main.ts \ + --build-timeout 5 --build-memory-limit 1024 --region us +``` + +**Fresh app (framework auto-detected):** + +```bash +deno deploy create \ + --org my-org --app my-fresh-app \ + --source local \ + --build-timeout 5 --build-memory-limit 1024 --region us +``` + +**Next.js from GitHub:** + +```bash +deno deploy create \ + --org my-org --app my-next-app \ + --source github --owner my-github-user --repo my-next-repo \ + --framework-preset Next \ + --build-timeout 15 --build-memory-limit 2048 --region us \ + --allow-node-modules +``` + +**Static site:** + +```bash +deno deploy create \ + --org my-org --app my-static-site \ + --source local \ + --runtime-mode static --static-dir dist --single-page-app \ + --build-command "deno task build" \ + --build-timeout 5 --build-memory-limit 1024 --region us +``` + +## Environment Variables + +### Contexts + +Deno Deploy has three "contexts" - logical environments where your code runs, +each with its own set of variables: + +| Context | Purpose | +| --------------- | --------------------------------------- | +| **Production** | Live traffic on your production URL | +| **Development** | Preview deployments and branch URLs | +| **Build** | Only available during the build process | + +You can set different values for the same variable in each context. For example, +you might use a test database URL in Development and the real one in Production. + +### Predefined Variables + +These are automatically available in your code: + +| Variable | Description | +| -------------------- | -------------------------------------- | +| `DENO_DEPLOY` | Always `1` when running on Deno Deploy | +| `DENO_DEPLOYMENT_ID` | Unique ID for the current deployment | +| `DENO_DEPLOY_ORG_ID` | Your organization's ID | +| `DENO_DEPLOY_APP_ID` | Your application's ID | +| `CI` | Set to `1` during builds only | + +### Accessing Variables in Code + +```typescript +const dbUrl = Deno.env.get("DATABASE_URL"); +const isDenoDeploy = Deno.env.get("DENO_DEPLOY") === "1"; +``` + +### Managing Variables via CLI + +```bash +# Add a plain text variable +deno deploy env add DATABASE_URL "postgres://..." + +# Add a secret variable (hidden after creation, only readable in code) +deno deploy env add API_KEY "sk-..." --secret + +# List all variables +deno deploy env list + +# Update just the value (keeps contexts and secret status) +deno deploy env update-value DATABASE_URL "postgres://new-url..." + +# Update which contexts a variable applies to +deno deploy env update-contexts DATABASE_URL production development + +# Delete a variable +deno deploy env delete DATABASE_URL + +# Load from .env file (all values treated as secrets by default) +deno deploy env load .env.production + +# Load from .env file, marking specific keys as non-secrets +deno deploy env load .env.production --non-secrets PUBLIC_URL APP_NAME +``` + +### Variable Types + +- **Plain text** - Visible in the dashboard, good for feature flags and + non-sensitive config +- **Secrets** - Hidden after creation, only readable in your code, use for API + keys and credentials + +### Limits + +- Key names: max 128 bytes +- Values: max 16 KB +- Keys cannot start with `DENO_`, `LD_`, or `OTEL_` + +## Viewing Logs + +```bash +# Stream live logs +deno deploy logs + +# Filter by date range +deno deploy logs --start 2026-01-15 --end 2026-01-16 +``` + +## Databases & Storage + +Deno Deploy provides built-in database support with **automatic environment +isolation**. Each environment (production, preview, branch) gets its own +isolated database automatically. + +### Available Options + +| Engine | Use Case | +| -------------- | -------------------------------------------------------- | +| **Deno KV** | Key-value storage, simple data, counters, sessions | +| **PostgreSQL** | Relational data, complex queries, existing Postgres apps | + +### Deno KV Quick Start + +No configuration needed - just use the built-in API: + +```typescript +const kv = await Deno.openKv(); + +// Store data +await kv.set(["users", "alice"], { name: "Alice", role: "admin" }); + +// Retrieve data +const user = await kv.get(["users", "alice"]); +console.log(user.value); // { name: "Alice", role: "admin" } + +// List by prefix +for await (const entry of kv.list({ prefix: ["users"] })) { + console.log(entry.key, entry.value); +} +``` + +Deno Deploy automatically connects to the correct database based on your +environment. + +### PostgreSQL + +For PostgreSQL, Deno Deploy injects environment variables (`DATABASE_URL`, +`PGHOST`, etc.) that most libraries detect automatically: + +```typescript +// Recommended: npm:pg (best PostgreSQL driver for Deno Deploy) +import pg from "npm:pg"; +const pool = new pg.Pool(); // Reads DATABASE_URL from environment automatically +``` + +### Provisioning + +Use the `deno deploy database` command to provision and manage databases: + +```bash +# Provision a Deno KV database +deno deploy database provision my-database --kind denokv + +# Provision a Prisma PostgreSQL database +deno deploy database provision my-database --kind prisma --region us-east-1 + +# Assign to your app +deno deploy database assign my-database --app my-app +``` + +For detailed CLI commands, see [Databases](references/DATABASES.md). + +### Local Development + +Use `--tunnel` to connect to your hosted development database locally: + +```bash +deno task --tunnel dev +``` + +See [Databases](references/DATABASES.md) and [Deno KV](references/DENO_KV.md) +for detailed documentation. + +## Local Development Tunnel + +The tunnel feature lets you expose your local development server to the +internet. This is useful for: + +- **Testing webhooks** - Receive webhook callbacks from external services +- **Sharing with teammates** - Let others preview your local work +- **Mobile testing** - Access your local server from other devices + +### Basic Usage + +Add the `--tunnel` flag when running your app: + +```bash +deno run --tunnel -A main.ts +``` + +The first time you run this, it will: + +1. Ask you to authenticate with Deno Deploy (opens a browser) +2. Ask you to select which app to connect the tunnel to +3. Generate a public URL that forwards requests to your local server + +### Using with Tasks + +You can use `--tunnel` with your existing tasks in `deno.json`: + +```bash +deno task --tunnel dev +``` + +This runs your `dev` task with the tunnel enabled. + +### What the Tunnel Provides + +Beyond just forwarding requests, the tunnel also: + +- **Syncs environment variables** - Variables set in your Deno Deploy app's + "Local" context become available to your local process +- **Sends logs and metrics** - OpenTelemetry data goes to the Deno Deploy + dashboard (filter with `context:local`) +- **Connects to databases** - Automatically connects to your assigned local + development databases + +### Managing Tunnels + +- View active tunnels in the Deno Deploy dashboard under the "Tunnels" tab +- Stop a tunnel by terminating the Deno process (Ctrl+C) + +## Command Reference + +| Command | Purpose | +| ----------------------------------------------------- | ------------------------------------------------------ | +| `deno deploy --prod` | Deploy to production (app must exist first) | +| `deno deploy` | Preview deployment | +| `deno deploy create --org ` | Create new app (interactive) | +| `deno deploy create --org --app ...` | Create new app (non-interactive, see full flags above) | +| `deno deploy create ... --no-wait` | Create app without waiting for build to complete | +| `deno deploy create ... --allow-node-modules` | Create app including node_modules | +| `deno deploy env add ` | Add plain text environment variable | +| `deno deploy env add --secret` | Add secret environment variable | +| `deno deploy env list` | List environment variables | +| `deno deploy env update-value ` | Update variable value (keeps contexts/secret status) | +| `deno deploy env update-contexts ` | Update which contexts a variable applies to | +| `deno deploy env delete ` | Delete environment variable | +| `deno deploy env load ` | Load variables from .env file (defaults to secret) | +| `deno deploy env load --non-secrets ` | Load .env file, marking specific keys as non-secrets | +| `deno deploy database provision --kind ` | Provision a new database | +| `deno deploy database assign --app ` | Assign database to an app | +| `deno deploy logs` | View deployment logs | +| `deno run --tunnel -A ` | Start local tunnel | +| `deno task --tunnel ` | Run task with tunnel | + +## Edge Runtime Notes + +Deno Deploy runs in one or many regions (globally distributed). Keep in mind: + +- **Environment variables** - Must be set via `deno deploy env`, not .env files + at runtime +- **Global distribution** - Code runs at the region closest to users +- **Cold starts** - First request after idle may be slightly slower + +## Additional References + +- [Authentication](references/AUTHENTICATION.md) - Interactive and CI/CD + authentication +- [Databases](references/DATABASES.md) - Database provisioning and connections +- [Deno KV](references/DENO_KV.md) - Key-value storage API and examples +- [Domains](references/DOMAINS.md) - Custom domains and SSL certificates +- [Frameworks](references/FRAMEWORKS.md) - Framework-specific deployment guides +- [Organizations](references/ORGANIZATIONS.md) - Managing orgs and members +- [Runtime](references/RUNTIME.md) - Lifecycle, cold starts, and limitations +- [Troubleshooting](references/TROUBLESHOOTING.md) - Common issues and solutions + +## Documentation + +- Official docs: https://docs.deno.com/deploy/ +- CLI reference: https://docs.deno.com/runtime/reference/cli/deploy/ +- Databases: https://docs.deno.com/deploy/reference/databases/ +- Deno KV: https://docs.deno.com/deploy/reference/deno_kv/ +- Domains: https://docs.deno.com/deploy/reference/domains/ +- Environment variables & contexts: + https://docs.deno.com/deploy/reference/env_vars_and_contexts/ +- Organizations: https://docs.deno.com/deploy/reference/organizations/ +- Runtime: https://docs.deno.com/deploy/reference/runtime/ +- Tunnel: https://docs.deno.com/deploy/reference/tunnel/ diff --git a/plugins/deno/.agents/skills/deno-deploy/references/AUTHENTICATION.md b/plugins/deno/.agents/skills/deno-deploy/references/AUTHENTICATION.md new file mode 100644 index 00000000..4fd9e7fb --- /dev/null +++ b/plugins/deno/.agents/skills/deno-deploy/references/AUTHENTICATION.md @@ -0,0 +1,185 @@ +# Deno Deploy Authentication + +## Interactive Authentication (Default) + +The first time you run `deno deploy`, it will open a browser for authentication: + +```bash +deno deploy +# Opens: https://console.deno.com/auth?code=XXXX-XXXX +``` + +**Important - Browser Device Authorization Flow:** + +- The CLI opens your browser and waits for you to complete authentication +- You must complete the authorization in your browser before the CLI can + continue +- The CLI will not proceed automatically - it waits until you finish +- Credentials are stored in your system keyring after successful auth + +**Note:** When running `deno deploy` commands that require authentication, the +user must complete the browser authorization before the deployment can proceed. + +## Non-Interactive Authentication (CI/CD & Automation) + +To deploy without browser interaction (for CI/CD pipelines or automated +workflows): + +### 1. Create a Deploy Token + +1. Visit https://console.deno.com/account/access-tokens +2. Click "New Access Token" +3. Give it a descriptive name (e.g., "GitHub Actions CI") +4. Copy the token immediately (shown only once) + +### 2. Use the Token + +```bash +# Option 1: Environment variable (recommended for CI/CD) +export DENO_DEPLOY_TOKEN="your-token-here" +deno deploy --prod + +# Option 2: Inline flag (for one-off commands) +deno deploy --token "your-token-here" --prod +``` + +### 3. GitHub Actions Example + +```yaml +- name: Deploy to Deno Deploy + env: + DENO_DEPLOY_TOKEN: ${{ secrets.DENO_DEPLOY_TOKEN }} + run: deno deploy --prod +``` + +If the app doesn't exist yet, create it first in CI/CD using non-interactive +flags: + +```yaml +- name: Create and deploy app + env: + DENO_DEPLOY_TOKEN: ${{ secrets.DENO_DEPLOY_TOKEN }} + run: | + deno deploy create \ + --org my-org --app my-app \ + --source local \ + --runtime-mode dynamic --entrypoint main.ts \ + --build-timeout 10 --build-memory-limit 2048 --region us +``` + +After the app is created, subsequent deploys only need `deno deploy --prod`. + +**Tip:** For fully automated deploys without browser prompts, ensure a Deno +Deploy access token is set up. Create one at +https://console.deno.com/account/access-tokens, then set it as the +`DENO_DEPLOY_TOKEN` environment variable. + +## Finding Your Organization Name + +The Deno Deploy CLI requires an organization context for most operations. To +find your org name: + +1. Visit https://console.deno.com +2. Your org is in the URL: `console.deno.com/YOUR-ORG-NAME` + +**Note:** Commands like `deno deploy orgs` and `deno deploy switch` require an +existing org context to work - this is a CLI limitation. Always find your org +name from the console URL first. + +## Setting Up Your First App + +**Before creating:** Check if an app already exists: + +```bash +cat deno.json | grep -A5 '"deploy"' +``` + +If no deploy config exists, you need to create the app first. Apps must be +created before they can be deployed to. + +**Interactive creation** (opens a browser): + +```bash +deno deploy create --org your-org-name +``` + +This opens a browser to create the app. **Important:** + +- Complete the app creation in your browser +- The CLI waits until you finish - it won't proceed automatically +- The app name becomes your URL: `.deno.dev` + +**Non-interactive creation** (for AI agents and CI/CD — no browser needed): + +```bash +deno deploy create \ + --org your-org-name \ + --app your-app-name \ + --source local \ + --runtime-mode dynamic \ + --entrypoint main.ts \ + --build-timeout 5 \ + --build-memory-limit 1024 \ + --region us +``` + +This creates the app and does the initial deploy in one step. No browser +interaction required. See the main skill doc for the full list of `create` +flags. + +**Verifying Success:** After completion, verify by checking deno.json: + +```bash +cat deno.json | grep -A5 '"deploy"' +``` + +You should see: + +```json +"deploy": { + "org": "your-org-name", + "app": "your-app-name" +} +``` + +After this, subsequent deploys only need: + +```bash +deno deploy --prod +``` + +## Interactive Commands + +Some `deno deploy` commands are interactive and cannot be run through automated +tools. + +### Switching Organizations/Apps + +```bash +deno deploy switch +``` + +This opens an interactive menu to select org and app. + +**Alternative - Use Explicit Flags:** + +Instead of interactive selection, specify org/app directly: + +```bash +deno deploy --org your-org-name --app your-app-name --prod +``` + +This bypasses the interactive flow. + +## Commands That Fail Without Org Context + +These commands will error if no org is configured: + +- `deno deploy` (without --org flag) +- `deno deploy orgs` +- `deno deploy switch` +- `deno deploy env list` +- `deno deploy logs` + +Always ensure org context is set via deno.json or --org flag before running +these commands. diff --git a/plugins/deno/.agents/skills/deno-deploy/references/DATABASES.md b/plugins/deno/.agents/skills/deno-deploy/references/DATABASES.md new file mode 100644 index 00000000..45bb89e0 --- /dev/null +++ b/plugins/deno/.agents/skills/deno-deploy/references/DATABASES.md @@ -0,0 +1,159 @@ +# Databases on Deno Deploy + +## Overview + +Deno Deploy provides built-in database support with automatic environment +isolation. You don't need to manage connection strings or worry about mixing +production and development data. + +## Available Database Engines + +| Engine | Description | +| -------------- | -------------------------------------------------------------------- | +| **Deno KV** | Fast, globally distributed key-value store hosted by Deno | +| **PostgreSQL** | Connect your own PostgreSQL or provision managed Postgres via Prisma | + +## Key Concept: Timelines + +Deno Deploy automatically creates **isolated databases for each environment**: + +- **Production:** `{app-id}-production` +- **Git branches:** `{app-id}--{branch-name}` +- **Preview deployments:** `{app-id}-preview` + +This means your preview deployments won't accidentally modify production data. + +## Database CLI Commands + +Use `deno deploy database` to manage databases from the command line. + +### List Databases + +```bash +# List all databases in your organization +deno deploy database list + +# Search for databases by name +deno deploy database list my-prefix +``` + +### Provision a Database + +Create a new managed database: + +```bash +# Provision a new Deno KV database +deno deploy database provision my-database --kind denokv + +# Provision a new Prisma PostgreSQL database (requires --region) +deno deploy database provision my-database --kind prisma --region us-east-1 +``` + +### Link an External Database + +Link an existing external postgres database by providing a connection string: + +```bash +deno deploy database link my-database "postgres://user:pass@host:5432/db" +``` + +### Assign / Detach + +Connect or disconnect a database from an app: + +```bash +# Assign a database to an app +deno deploy database assign my-database --app my-app + +# Detach a database from an app +deno deploy database detach my-database --app my-app +``` + +Deno Deploy creates separate databases for each timeline automatically. + +### Query a Database + +Run queries directly from the CLI: + +```bash +deno deploy database query my-database production "SELECT * FROM users LIMIT 10" +``` + +The second argument is the timeline name (e.g., `production`, `preview`, or a +branch name), which can be found in the output of `deno deploy database list`. + +### Delete a Database + +```bash +deno deploy database delete my-database +``` + +## Connecting in Code + +### Deno KV + +No configuration needed - just call `Deno.openKv()`: + +```typescript +const kv = await Deno.openKv(); + +// Deno Deploy automatically connects to the right database +// based on your current environment (production, preview, etc.) +``` + +### PostgreSQL + +Deno Deploy injects standard environment variables that most PostgreSQL +libraries detect automatically: + +- `DATABASE_URL` - Full connection string +- `PGHOST`, `PGPORT`, `PGDATABASE`, `PGUSER`, `PGPASSWORD` - Individual + components + +```typescript +// Recommended: npm:pg (best PostgreSQL driver for Deno Deploy) +import pg from "npm:pg"; +const pool = new pg.Pool(); // Reads DATABASE_URL from environment automatically +const { rows } = await pool.query("SELECT * FROM users"); +``` + +## Local Development + +### With Tunnel + +Use `--tunnel` to connect your local dev server to your hosted development +database: + +```bash +deno task --tunnel dev +``` + +This gives you access to the same database environment variables locally. + +### Without Tunnel + +- **Deno KV:** Data stays in memory during local development +- **PostgreSQL:** Point to a local PostgreSQL instance or use the tunnel + +## Migrations + +Deno Deploy supports pre-deploy commands that run before each deployment. Use +these for database migrations: + +```json +{ + "deploy": { + "preDeploy": ["deno task db:migrate"] + } +} +``` + +## Sharing Databases + +Multiple apps can share the same database instance. Each app gets its own +isolated databases per timeline, even when sharing. + +## Documentation + +- Databases overview: https://docs.deno.com/deploy/reference/databases/ +- Deno KV reference: https://docs.deno.com/deploy/reference/deno_kv/ diff --git a/plugins/deno/.agents/skills/deno-deploy/references/DENO_KV.md b/plugins/deno/.agents/skills/deno-deploy/references/DENO_KV.md new file mode 100644 index 00000000..309144cd --- /dev/null +++ b/plugins/deno/.agents/skills/deno-deploy/references/DENO_KV.md @@ -0,0 +1,153 @@ +# Deno KV + +## What is Deno KV? + +Deno KV is a key-value database built into Deno. On Deno Deploy, it's a fast, +globally distributed store that requires no setup or configuration. + +## Quick Start + +```typescript +// Open the KV store (auto-connects on Deno Deploy) +const kv = await Deno.openKv(); + +// Store a value +await kv.set(["users", "alice"], { name: "Alice", email: "alice@example.com" }); + +// Retrieve a value +const result = await kv.get(["users", "alice"]); +console.log(result.value); // { name: "Alice", email: "alice@example.com" } + +// Delete a value +await kv.delete(["users", "alice"]); +``` + +## Keys + +Keys are arrays of "key parts" that form a hierarchy: + + +```typescript +// Simple key +["settings"] + +// Hierarchical keys +["users", "alice"] +["users", "bob"] +["posts", "2024", "01", "my-post"] +``` + +Key parts can be strings, numbers, booleans, Uint8Array, or bigints. + +## Basic Operations + +### Get + +```typescript +const result = await kv.get(["users", "alice"]); +if (result.value) { + console.log(result.value.name); +} +``` + +### Set + +```typescript +await kv.set(["users", "alice"], { name: "Alice" }); + +// With expiration (in milliseconds) +await kv.set(["sessions", sessionId], data, { expireIn: 3600000 }); // 1 hour +``` + +### Delete + +```typescript +await kv.delete(["users", "alice"]); +``` + +### List + +```typescript +// List all users +const users = kv.list({ prefix: ["users"] }); +for await (const entry of users) { + console.log(entry.key, entry.value); +} + +// With limit +const firstTen = kv.list({ prefix: ["users"] }, { limit: 10 }); +``` + +## Atomic Transactions + +Perform multiple operations atomically (all succeed or all fail): + +```typescript +// Transfer credits between users +const alice = await kv.get(["credits", "alice"]); +const bob = await kv.get(["credits", "bob"]); + +const result = await kv.atomic() + .check(alice) // Ensure alice hasn't changed + .check(bob) // Ensure bob hasn't changed + .set(["credits", "alice"], alice.value! - 100) + .set(["credits", "bob"], bob.value! + 100) + .commit(); + +if (!result.ok) { + console.log("Transaction failed - data was modified"); +} +``` + +## Example: Request Counter + +```typescript +const kv = await Deno.openKv(); + +Deno.serve(async () => { + // Increment counter atomically + const key = ["requests"]; + + let result = { ok: false }; + while (!result.ok) { + const current = await kv.get(key); + const newCount = (current.value ?? 0) + 1; + + result = await kv.atomic() + .check(current) + .set(key, newCount) + .commit(); + } + + const count = (await kv.get(key)).value; + return new Response(`Requests: ${count}`); +}); +``` + +## Data Location + +On Deno Deploy, KV data is replicated across at least three data centers in +Northern Virginia (us-east-4). Cross-region replication is not currently +available. + +## Local Development + +When running locally with `deno run`, KV data is stored in memory by default. +For persistent local storage: + +```typescript +// Persist to a local file +const kv = await Deno.openKv("./my-database.sqlite"); +``` + +## Important Notes + +- **Deletion is permanent** - Deleting a KV instance removes all data with no + recovery +- **Back up important data** before deleting instances +- **No cross-region replication** yet - data lives in us-east-4 + +## Documentation + +- Deno KV on Deploy: https://docs.deno.com/deploy/reference/deno_kv/ +- Deno KV API: https://docs.deno.com/api/deno/~/Deno.Kv diff --git a/plugins/deno/.agents/skills/deno-deploy/references/DOMAINS.md b/plugins/deno/.agents/skills/deno-deploy/references/DOMAINS.md new file mode 100644 index 00000000..bf0351e9 --- /dev/null +++ b/plugins/deno/.agents/skills/deno-deploy/references/DOMAINS.md @@ -0,0 +1,93 @@ +# Custom Domains + +## Default Domain + +Every organization gets a default domain: `your-org.deno.net` + +Apps are accessible at: `your-app.deno.dev` + +## Adding a Custom Domain + +1. Go to your organization's domains page in the Deno Deploy dashboard +2. Click "Add Domain" +3. Enter your domain (e.g., `example.com` or `*.example.com` for wildcards) +4. Click "Add Domain" to see DNS configuration + +## DNS Configuration + +You have three options for DNS setup: + +### Option 1: ANAME/ALIAS (Recommended) + +Best option if your registrar supports ANAME or ALIAS records. + +| Record Type | Name | Value | +| ----------- | ----------------- | ----------------------- | +| ANAME/ALIAS | `@` | `.deno.dev` | +| CNAME | `_acme-challenge` | (provided in dashboard) | + +### Option 2: CNAME + +Works for subdomains (like `api.example.com`) but **not for apex domains** (like +`example.com`). + +| Record Type | Name | Value | +| ----------- | --------------------- | ----------------------- | +| CNAME | `api` | `.deno.dev` | +| CNAME | `_acme-challenge.api` | (provided in dashboard) | + +### Option 3: A Record + +Most compatible, works with any registrar. + +| Record Type | Name | Value | +| ----------- | ----------------- | -------------------------- | +| A | `@` | (IP provided in dashboard) | +| CNAME | `_acme-challenge` | (provided in dashboard) | + +**Note:** IPv6 is not supported with the A record method. + +## Cloudflare Users + +If using Cloudflare, **disable proxying** (turn off the orange cloud) on the +`_acme-challenge` CNAME record. Proxying prevents certificate verification from +completing. + +## SSL/TLS Certificates + +### Automatic Certificates (Recommended) + +After DNS verification completes: + +1. Click "Provision Certificate" in the dashboard +2. Let's Encrypt generates your certificate +3. Certificates renew automatically + +### Bring Your Own Certificate + +If you need a specific certificate: + +1. Upload your PEM-formatted certificate file +2. Upload your private key file +3. **You must manage renewal** - notifications arrive 14 days before expiration + +**Warning:** Expired certificates cause your domain to stop working. + +## Assigning Domains to Apps + +1. Go to organization domains page +2. Find your domain and click to edit +3. Assign it to an application +4. Remove assignments from app settings if needed + +## Troubleshooting + +| Issue | Solution | +| --------------------------- | --------------------------------------------------------- | +| Verification stuck | Check DNS propagation (can take up to 48 hours) | +| Certificate won't provision | Ensure `_acme-challenge` CNAME is correct and not proxied | +| IPv6 not working | Use ANAME/ALIAS or CNAME instead of A record | + +## Documentation + +- Domains reference: https://docs.deno.com/deploy/reference/domains/ diff --git a/plugins/deno/.agents/skills/deno-deploy/references/FRAMEWORKS.md b/plugins/deno/.agents/skills/deno-deploy/references/FRAMEWORKS.md new file mode 100644 index 00000000..e7cb31a1 --- /dev/null +++ b/plugins/deno/.agents/skills/deno-deploy/references/FRAMEWORKS.md @@ -0,0 +1,215 @@ +# Framework-Specific Deployment + +Deno Deploy supports multiple frameworks. The CLI auto-detects your framework +and configures the build appropriately. + +## Framework Detection + +| Framework | Detection Files | Build Command | Notes | +| -------------- | ------------------------------------- | ------------------------------------ | --------------------------------- | +| **Fresh** | `islands/`, `fresh.config.ts` | `deno task build` | Deno-native, island architecture | +| **Astro** | `astro.config.mjs`, `astro.config.ts` | `npm run build` or `deno task build` | Static or SSR | +| **Next.js** | `next.config.js`, `next.config.mjs` | `npm run build` | Requires `nodeModulesDir: "auto"` | +| **Nuxt** | `nuxt.config.ts` | `npm run build` | Vue SSR framework | +| **Remix** | `remix.config.js` | `npm run build` | React SSR framework | +| **SolidStart** | `app.config.ts` with solid | `npm run build` | SolidJS SSR | +| **SvelteKit** | `svelte.config.js` | `npm run build` | Svelte SSR framework | +| **Lume** | `_config.ts` with lume import | `deno task build` | Deno-native static site | + +## Framework Presets for `deno deploy create` + +When creating an app with `deno deploy create` in non-interactive mode, you can +specify `--framework-preset` to auto-configure build commands and runtime +settings. The available presets are: `Fresh`, `Next`, `Remix`, `Astro`, +`SvelteKit`, `Nuxt`, `Lume`, `SolidStart`. + +When a preset is specified, you can omit `--install-command`, `--build-command`, +`--pre-deploy-command`, and `--runtime-mode` — they are inferred from the +preset. + +If you don't specify a preset, the CLI still auto-detects your framework from +the project files. Use `--do-not-use-detected-build-config` to skip +auto-detection and specify everything manually. + +## Detect Framework Script + +```bash +if [ -d "islands" ] || [ -f "fresh.config.ts" ]; then echo "Framework: Fresh"; \ +elif [ -f "astro.config.mjs" ] || [ -f "astro.config.ts" ]; then echo "Framework: Astro"; \ +elif [ -f "next.config.js" ] || [ -f "next.config.mjs" ]; then echo "Framework: Next.js"; \ +elif [ -f "nuxt.config.ts" ]; then echo "Framework: Nuxt"; \ +elif [ -f "remix.config.js" ]; then echo "Framework: Remix"; \ +elif [ -f "svelte.config.js" ]; then echo "Framework: SvelteKit"; \ +elif [ -f "_config.ts" ]; then echo "Framework: Lume (check imports)"; \ +else echo "Framework: Custom/Unknown"; fi +``` + +## Fresh (Deno-Native) + +```bash +deno task build +deno deploy --prod +``` + +## Fresh + PostgreSQL + +When a Fresh app uses PostgreSQL (e.g., `await initDb()` at startup), you must +provision the database **before** the app can successfully warm up. The Fresh +auto-detection preset also has a known issue, so use manual build config. + +**Complete deployment sequence:** + +```bash +# 1. Create the app with --no-wait (warmup will fail without a database — that's expected) +deno deploy create \ + --org --app \ + --source local \ + --do-not-use-detected-build-config \ + --install-command "deno install" \ + --build-command "deno task build" \ + --pre-deploy-command "echo ready" \ + --runtime-mode dynamic --entrypoint main.ts \ + --build-timeout 5 --build-memory-limit 1024 --region us \ + --no-wait + +# 2. Provision a PostgreSQL database +deno deploy database provision my-db --kind prisma --region us-east-1 + +# 3. Assign it to the app (this injects DATABASE_URL, PGHOST, etc.) +deno deploy database assign my-db --app + +# 4. Redeploy — now the database exists, so warmup succeeds +deno deploy --prod +``` + +**Why this order matters:** + +- Fresh + PostgreSQL apps typically call `await initDb()` in `main.ts`, which + runs during warmup +- If no database is assigned, the connection fails and the deploy is marked as + failed +- Using `--no-wait` on the first deploy lets you continue to the database setup + without blocking + +**Why `--do-not-use-detected-build-config`:** + +- The Fresh auto-detection and `--framework-preset fresh` can fail with an API + error +- Manual build config is more reliable — see + [Troubleshooting](TROUBLESHOOTING.md#fresh-auto-detection--preset-fails) + +## Astro + +```bash +# If using npm +npm run build +deno deploy --prod + +# If using Deno tasks +deno task build +deno deploy --prod +``` + +## Next.js + +Next.js requires Node.js compatibility mode: + +1. Ensure `deno.json` has: + ```json + { + "nodeModulesDir": "auto" + } + ``` + +2. Build and deploy: + ```bash + npm install + npm run build + deno deploy --prod --allow-node-modules + ``` + +## Nuxt / Remix / SvelteKit / SolidStart + +These npm-based frameworks follow a similar pattern: + +```bash +npm install +npm run build +deno deploy --prod +``` + +If you encounter issues with node_modules: + +```bash +deno deploy --prod --allow-node-modules +``` + +## Lume (Static Sites) + +```bash +deno task build +deno deploy --prod +``` + +## Custom / No Framework + +For custom servers or apps without a recognized framework: + +1. Ensure you have an entrypoint (e.g., `main.ts`, `server.ts`) +2. Deploy directly: + ```bash + deno deploy --entrypoint main.ts --prod + ``` + +## Static Site Deployment + +For static sites (Lume, Vite builds, etc.), you have two options: + +### Option 1: Direct Directory Deployment + +Point Deno Deploy at your built directory. Configure in `deno.json`: + +```json +{ + "deploy": { + "entrypoint": "main.ts", + "include": ["_site"] + } +} +``` + +### Option 2: Custom Server Wrapper + +Only needed if you want custom routing, headers, or logic: + +```typescript +// serve.ts +import { serveDir } from "jsr:@std/http/file-server"; + +Deno.serve((req) => + serveDir(req, { + fsRoot: "_site", + quiet: true, + }) +); +``` + +Then deploy with: + +```bash +deno deploy --entrypoint serve.ts --prod +``` + +## Cloud Integrations + +### AWS Integration + +```bash +deno deploy setup-aws --org my-org --app my-app +``` + +### GCP Integration + +```bash +deno deploy setup-gcp --org my-org --app my-app +``` diff --git a/plugins/deno/.agents/skills/deno-deploy/references/ORGANIZATIONS.md b/plugins/deno/.agents/skills/deno-deploy/references/ORGANIZATIONS.md new file mode 100644 index 00000000..cdebac30 --- /dev/null +++ b/plugins/deno/.agents/skills/deno-deploy/references/ORGANIZATIONS.md @@ -0,0 +1,86 @@ +# Organizations + +## What is an Organization? + +In Deno Deploy, an organization is a group where users collectively own apps and +domains. Every user belongs to an organization - all resources (apps, domains, +environment variables) exist at the organization level. + +Each organization has: + +- **Name:** Displayed in the dashboard +- **Slug:** Part of your default domain (e.g., `acme-inc.deno.net`) + +**Important:** The slug cannot be changed after creation. + +## Creating an Organization + +Organizations are created automatically during Deno Deploy signup: + +1. Visit https://console.deno.com +2. Sign in with GitHub +3. Create your organization as part of setup + +## Finding Your Organization + +Your org name appears in the console URL: + +``` +https://console.deno.com/YOUR-ORG-NAME +``` + +Use this for CLI commands: + +```bash +deno deploy create --org YOUR-ORG-NAME +deno deploy --org YOUR-ORG-NAME --prod +``` + +## Managing Members + +### Inviting Users + +1. Go to organization settings in the dashboard +2. Click "+ Invite User" +3. Enter the person's GitHub username (e.g., `ry`) +4. Optionally add their email address +5. Send the invitation + +The invitee receives an email with a link to accept. + +### Removing Members + +1. Go to organization settings +2. Find the user in the members table +3. Click remove and confirm + +### Canceling Invitations + +Pending invitations can be cancelled before the person accepts. + +## Permissions + +Currently, **all members have owner permissions**. Every member can: + +- Invite and remove other members +- Create and delete apps +- Manage domains +- Configure environment variables +- Deploy to production + +There is no tiered permission system yet. + +## Organization Deletion + +Organizations **cannot be deleted through the dashboard**. Contact Deno support +if you need to delete an organization. + +## Best Practices + +- **Choose your slug carefully** - it's permanent and visible in URLs +- **Limit membership** - since all members have full access +- **Use descriptive app names** - they become part of URLs too + +## Documentation + +- Organizations reference: https://docs.deno.com/deploy/reference/organizations/ diff --git a/plugins/deno/.agents/skills/deno-deploy/references/RUNTIME.md b/plugins/deno/.agents/skills/deno-deploy/references/RUNTIME.md new file mode 100644 index 00000000..4077d1c3 --- /dev/null +++ b/plugins/deno/.agents/skills/deno-deploy/references/RUNTIME.md @@ -0,0 +1,103 @@ +# Deno Deploy Runtime + +## Overview + +Deno Deploy uses the standard Deno runtime. You can use JSR and NPM packages, +filesystem operations, network requests, subprocesses, and FFI/native addons. + +## Current Environment + +- **Runtime:** Deno 2.5.0 +- **Platform:** Linux (x64 or ARM64) +- **Permissions:** All permissions enabled automatically (`--allow-all`) + +**Note:** Custom Deno flags cannot be passed to the runtime. + +## Serverless Lifecycle + +Understanding how your app starts and stops is important for building reliable +applications. + +### Startup + +Your application starts when a request arrives. If your app crashes before the +HTTP server starts, requests return a 502 error. + +**Tip:** Keep startup fast by: + +- Reducing dependencies +- Using dynamic imports for rarely-used code +- Avoiding network requests during startup + +### Idle Shutdown + +After 5-10 minutes without requests: + +1. The system sends a `SIGINT` signal +2. Your app has 5 seconds to shut down gracefully +3. If still running, `SIGKILL` terminates it + +```typescript +// Handle graceful shutdown +Deno.addSignalListener("SIGINT", () => { + console.log("Shutting down..."); + // Clean up resources, close connections + Deno.exit(0); +}); +``` + +### Eviction + +Even during active traffic, instances may be terminated due to: + +- Infrastructure updates +- Resource constraints + +The system redirects traffic first, then signals shutdown. **Long-running +connections should expect reconnections.** + +## Cold Start Performance + +Cold starts typically complete: + +- **~100ms** for simple "hello world" apps +- **A few hundred ms** for larger applications + +Deno Deploy optimizes cold starts using: + +- Pre-provisioned microVMs +- Early TCP connection setup +- File system warmup + +### Minimizing Cold Start Time + +```typescript +// BAD: Top-level network request delays startup +const config = await fetch("https://api.example.com/config").then((r) => + r.json() +); + +// GOOD: Lazy load on first request +let config: Config | null = null; +async function getConfig() { + if (!config) { + config = await fetch("https://api.example.com/config").then((r) => + r.json() + ); + } + return config; +} +``` + +## Limitations + +| Feature | Status | +| ----------------------------- | ------------------------ | +| Custom Deno flags | Not supported | +| Persistent filesystem | Use Deno KV instead | +| Long-running background tasks | May be interrupted | +| System tools | Available but may change | + +## Documentation + +- Runtime reference: https://docs.deno.com/deploy/reference/runtime/ diff --git a/plugins/deno/.agents/skills/deno-deploy/references/TROUBLESHOOTING.md b/plugins/deno/.agents/skills/deno-deploy/references/TROUBLESHOOTING.md new file mode 100644 index 00000000..066f2947 --- /dev/null +++ b/plugins/deno/.agents/skills/deno-deploy/references/TROUBLESHOOTING.md @@ -0,0 +1,191 @@ +# Deno Deploy Troubleshooting + +## First Step: Use `--help` + +Before debugging a failed command, run `--help` to confirm the flags you're +using actually exist and are spelled correctly: + +```bash +deno deploy create --help +deno deploy env --help +deno deploy database --help +``` + +Exit code 2 almost always means a flag is missing or invalid — `--help` will +show you exactly what's required. + +## Common Errors + +### "No organization was selected" + +This error occurs because the CLI needs an organization context. Unfortunately, +commands like `deno deploy orgs` also fail without this context. + +**Solution:** + +1. **Find your org name manually:** Visit https://console.deno.com - your org is + in the URL path (e.g., `console.deno.com/donjo` means org is `donjo`) + +2. **Specify org explicitly:** + ```bash + deno deploy --org your-org-name --prod + ``` + +3. **Or create an app with org:** + ```bash + deno deploy create --org your-org-name + # Complete the browser flow when prompted + ``` + +If you see this error, the user needs to provide their organization name from +the console URL. + +### "No entrypoint found" + +Specify your entry file: + +```bash +deno deploy --entrypoint main.ts --prod +``` + +Or add to `deno.json`: + +```json +{ + "deploy": { + "entrypoint": "main.ts" + } +} +``` + +### "authorization required" + +Token expired or missing. Options: + +- Re-authenticate interactively (browser flow) +- Set up a CI/CD token via `DENO_DEPLOY_TOKEN` environment variable +- Create a new token at https://console.deno.com/account/access-tokens + +### "Minimum Deno version required" + +User needs to upgrade Deno: + +```bash +deno upgrade +``` + +The `deno deploy` command requires Deno >= 2.4.2. + +### Fresh "Build required" Error + +Fresh 2.0 requires building before deployment: + +```bash +deno task build +deno deploy --prod +``` + +### Environment Variable Errors + +Check what's currently set: + +```bash +deno deploy env list +``` + +Add missing variables: + +```bash +deno deploy env add MISSING_VAR "value" +``` + +### Warmup Failure After Deploy + +The build succeeds but the deploy fails with a warmup error or exit code 1. This +usually means the app crashes on startup. + +**Most common cause:** The app connects to a database at startup (e.g., +`await initDb()` in `main.ts`), but no database has been provisioned or assigned +yet. + +**Solution:** + +1. 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 + ``` + +2. Redeploy: + ```bash + deno deploy --prod + ``` + +For a complete walkthrough, see the +[Fresh + PostgreSQL recipe](FRAMEWORKS.md#fresh--postgresql). + +### Fresh Auto-Detection / Preset Fails + +When the CLI auto-detects Fresh or you use `--framework-preset fresh`, the +deploy may fail with an API error. This is a known issue. + +**Workaround:** Use `--do-not-use-detected-build-config` and specify all build +commands manually: + +```bash +deno deploy create \ + --org --app \ + --source local \ + --do-not-use-detected-build-config \ + --install-command "deno install" \ + --build-command "deno task build" \ + --pre-deploy-command "echo ready" \ + --runtime-mode dynamic --entrypoint main.ts \ + --build-timeout 5 --build-memory-limit 1024 --region us +``` + +## Error Response Table + +| Error | Cause | Solution | +| ------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------ | +| "No organization was selected" | No org in config | Get org name from console URL, use `--org` flag | +| "No entrypoint found" | Can't find main file | Use `--entrypoint` flag or set in deno.json | +| "authorization required" | Token expired/missing | Re-authenticate or set `DENO_DEPLOY_TOKEN` | +| "Minimum Deno version required" | Deno too old | Run `deno upgrade` | +| Exit code 2 (usage error) | Missing or invalid flags | Run `deno deploy create --help` to see required flags | +| Warmup failure (exit code 1) | App crashes on startup | Check for missing database or env vars — see [Warmup Failure](#warmup-failure-after-deploy) | +| Fresh preset API error | Auto-detection bug | Use `--do-not-use-detected-build-config` — see [Fresh workaround](#fresh-auto-detection--preset-fails) | + +## Verifying Deployment Success + +The CLI output can be verbose. Look for these indicators of success: + +- A URL containing `.deno.dev` or `.deno.net` - this is your live deployment +- A console URL like `https://console.deno.com///builds/` +- The command exits with code 0 (no error) + +After deployment, confirm success by extracting the production URL from the +output. The format is typically: `https://..deno.net` or +`https://.deno.dev` + +## Commands That Require Org Context + +These commands will error if no org is configured - do not try them to +"discover" orgs: + +- `deno deploy` (without --org flag) +- `deno deploy orgs` +- `deno deploy switch` +- `deno deploy env list` +- `deno deploy logs` + +## Environment Variable Contexts + +Variables can apply to different environments: + +```bash +# Set which contexts a variable applies to +deno deploy env update-contexts API_KEY Production Preview +``` + +Available contexts: `Production`, `Preview`, `Local`, `Build` diff --git a/plugins/deno/.agents/skills/deno-frontend/SKILL.md b/plugins/deno/.agents/skills/deno-frontend/SKILL.md new file mode 100644 index 00000000..53633347 --- /dev/null +++ b/plugins/deno/.agents/skills/deno-frontend/SKILL.md @@ -0,0 +1,86 @@ +--- +name: deno-frontend +description: Use when building a web frontend with Deno — running React, Vite, Astro, SvelteKit, Next.js, Nuxt or other npm frameworks under Deno, or working with Fresh, Deno's own island-architecture framework. Covers which path to pick, Fresh 2.x routes, handlers, islands, Preact signals, Tailwind, and Fresh 1.x to 2.x migration. +license: MIT +metadata: + author: denoland + version: "3.0" +--- + +# Frontend development with Deno + +Two paths. Pick by what the project already uses. + +## Regular npm frameworks — the usual choice + +Deno runs the normal frontend ecosystem: React, Vue, Svelte, Solid, Vite, Astro, +Next.js, Nuxt, SvelteKit, Remix, SolidStart. Nothing needs to be ported, and +there is no Deno-specific way to write them. + +```bash +deno create vite my-app # or astro, next, nuxt, svelte… +cd my-app +deno install +deno task dev +``` + +`deno create` is `npm create`. `deno install` reads `package.json`. +`deno task