From 2f78f8f1697d7ef6e37699c7dfe24f33ec2bca7b Mon Sep 17 00:00:00 2001 From: Pedro Rodrigues Date: Fri, 30 Jan 2026 13:29:34 +0000 Subject: [PATCH] feat: add getting-started-locally guide with npx CLI workflow - Add references/getting-started-locally.md for local development - Update SKILL.md with Local Development reference - Add CLI usage note recommending npx for version consistency Co-Authored-By: Claude Opus 4.5 --- skills/supabase/AGENTS.md | 5 +- skills/supabase/SKILL.md | 11 +- .../references/getting-started-locally.md | 155 ++++++++++++++++++ 3 files changed, 166 insertions(+), 5 deletions(-) create mode 100644 skills/supabase/references/getting-started-locally.md diff --git a/skills/supabase/AGENTS.md b/skills/supabase/AGENTS.md index 4f7832e..85ae623 100644 --- a/skills/supabase/AGENTS.md +++ b/skills/supabase/AGENTS.md @@ -67,6 +67,9 @@ Reference files are named `{prefix}-{topic}.md` (e.g., `query-missing-indexes.md - `references/db/security-functions.md` - `references/db/security-service-role.md` +**getting** (`getting-`): +- `references/getting-started-locally.md` + --- -*18 reference files across 6 categories* \ No newline at end of file +*19 reference files across 6 categories* \ No newline at end of file diff --git a/skills/supabase/SKILL.md b/skills/supabase/SKILL.md index bf4ec48..8adf649 100644 --- a/skills/supabase/SKILL.md +++ b/skills/supabase/SKILL.md @@ -33,10 +33,11 @@ Reference the appropriate resource file based on the user's needs: ### Core Guides -| Area | Resource | When to Use | -| ---------------- | -------------------------------- | -------------------------------------------------------- | -| Getting Started | `references/getting-started.md` | Setting up a project, connection strings, dependencies | -| Referencing Docs | `references/referencing-docs.md` | Looking up official documentation, verifying information | +| Area | Resource | When to Use | +| ----------------- | --------------------------------------- | -------------------------------------------------------- | +| Getting Started | `references/getting-started.md` | Setting up a project, connection strings, dependencies | +| Local Development | `references/getting-started-locally.md` | Local CLI workflow with npx, Docker setup | +| Referencing Docs | `references/referencing-docs.md` | Looking up official documentation, verifying information | ### Authentication & Security @@ -82,3 +83,5 @@ Reference the appropriate resource file based on the user's needs: | supabase-js | `references/supabase-js.md` | JavaScript/TypeScript SDK, client config | | Supabase CLI | `references/cli.md` | Local development, migrations, CI/CD | | MCP Server | `references/mcp.md` | AI agent integration, MCP tooling | + +**CLI Usage:** Always use `npx supabase` instead of `supabase` for version consistency across team members. See `references/getting-started-locally.md` for the local development workflow. diff --git a/skills/supabase/references/getting-started-locally.md b/skills/supabase/references/getting-started-locally.md new file mode 100644 index 0000000..2645dcc --- /dev/null +++ b/skills/supabase/references/getting-started-locally.md @@ -0,0 +1,155 @@ +--- +title: Getting Started with Supabase CLI Locally +impact: CRITICAL +impactDescription: Local development workflow guide using Supabase CLI with npx +tags: cli, local, development, setup, workflow, npx +--- + +## Getting Started with Supabase CLI Locally + +Quick workflow guide for local Supabase development. References detailed command documentation. + +**Incorrect:** + +```bash +# Using installed CLI without consistency +supabase start # Version may differ across team +``` + +**Correct:** + +```bash +# Use npx for version consistency +npx supabase start +``` + +--- + +## Prerequisites + +- Docker Desktop (7GB+ RAM) +- Node.js 18+ (for npx) + +No global Supabase CLI installation needed when using npx. + +--- + +## Quick Start Workflow + +**1. Initialize project:** +```bash +npx supabase init +``` +See [cli-project-commands.md](cli-project-commands.md#supabase-init) for details. + +**2. Start local stack:** +```bash +npx supabase start +``` +See [cli-project-commands.md](cli-project-commands.md#supabase-start) for flags and options. + +**3. Get connection info:** +```bash +npx supabase status +``` +See [cli-project-commands.md](cli-project-commands.md#supabase-status) for output formats. + +--- + +## Development Workflow + +### Schema Development + +1. Create migration: +```bash +npx supabase migration new table_name +``` + +2. Apply locally: +```bash +npx supabase db reset +``` + +See [cli-migration-commands.md](cli-migration-commands.md) for migration workflow details. + +### Type Generation + +```bash +npx supabase gen types typescript --local > types/supabase.ts +``` + +See [cli-generation-commands.md](cli-generation-commands.md) for type generation options. + +### Edge Functions + +```bash +npx supabase functions new function-name +npx supabase functions serve +``` + +See [cli-functions-commands.md](cli-functions-commands.md) for function development details. + +--- + +## Connecting to Remote + +```bash +npx supabase login +npx supabase link --project-ref +``` + +See [cli-project-commands.md](cli-project-commands.md#supabase-link) for remote operations. + +--- + +## npx vs Global Install + +**npx** (recommended): +- No installation needed +- Version consistency across team +- Works with npm 5.2+ +- Always uses latest version + +**Global install** (not recommended): +- Requires `npm install -g supabase` or `brew install supabase` +- Version drift across team members +- Manual updates needed + +All commands in this skill use `npx` prefix. + +--- + +## Common Tasks + +```bash +# Daily development +npx supabase db reset # Apply migrations +npx supabase gen types typescript --local + +# Before committing +npx supabase db diff -f name # Capture schema changes + +# Deploying +npx supabase db push # Push migrations +npx supabase functions deploy # Deploy functions +``` + +--- + +## Decision Guide + +Not sure which command to use? See [cli-decision-guide.md](cli-decision-guide.md). + +Common pitfalls? See [cli-gotchas-pitfalls.md](cli-gotchas-pitfalls.md). + +--- + +## References + +- [cli-project-commands.md](cli-project-commands.md) - Init, start, stop, link +- [cli-database-commands.md](cli-database-commands.md) - DB operations +- [cli-migration-commands.md](cli-migration-commands.md) - Migration workflow +- [cli-functions-commands.md](cli-functions-commands.md) - Edge Functions +- [cli-generation-commands.md](cli-generation-commands.md) - Type generation +- [cli-decision-guide.md](cli-decision-guide.md) - Command selection +- [cli-gotchas-pitfalls.md](cli-gotchas-pitfalls.md) - Common issues