mirror of
https://github.com/supabase/supabase.git
synced 2026-10-06 09:55:06 +03:00
Wen Bo Xie
ffd2754c7a
Add two guides under Local Development for the experimental `supabase stack` commands, wire them into the docs nav, the CLI reference, the marketing features list, and the pages that readers reach with a port conflict. New pages: - guides/local-development/parallel-projects: run one local project per app, git worktree, branch, or named environment on a single machine. Covers identity, automatic port assignment, removing fixed ports from config.toml, named projects, finding endpoints, stop and destroy, the `[experimental] stack` setting, and current limitations. - guides/local-development/runtimes: the Docker and native runtimes, how the CLI picks one, native platform requirements, artifact download and cache locations, and runtime limitations. Cross-links and context: - Local development index, CLI getting started, CLI workflows, managing environments, AI tools, MCP, and the edge functions port troubleshooting entry now point readers to the new guides where a second `supabase start` fails on a port conflict. - CLI reference: `supabase stack`, `stack start`, `stack stop`, `stack destroy`, the `experimental.stack` config key, and a note on `supabase start` and `[experimental] stack`. - www: two feature entries and copy tweaks on the hosted Postgres and innovation teams solution pages. - supa-mdx-lint: allow worktree, glibc, musl, and checksum.
165 lines
5.9 KiB
Plaintext
165 lines
5.9 KiB
Plaintext
---
|
|
title: Local Development & CLI
|
|
subtitle: Learn how to develop locally and use the Supabase CLI
|
|
---
|
|
|
|
To develop your applications using the locally running Supabase stack, you'll need to install the [Supabase CLI](#cli) and a container runtime.
|
|
|
|
<Admonition type="note">
|
|
|
|
A container manager compatible with Docker APIs is a prerequisite for `supabase start`:
|
|
|
|
- [OrbStack](https://orbstack.dev/) (macOS) - recommended on macOS
|
|
- [Docker Desktop](https://docs.docker.com/desktop/) (macOS, Windows, Linux) - recommended on Windows and Linux
|
|
- [Rancher Desktop](https://rancherdesktop.io/) (macOS, Windows, Linux)
|
|
- [Podman](https://podman.io/) (macOS, Windows, Linux)
|
|
|
|
The experimental `supabase stack` commands can also run a local project as processes on your machine without Docker on Linux and on macOS on Apple silicon. See [Docker and native runtimes](/docs/guides/local-development/docker-and-native-runtimes).
|
|
|
|
</Admonition>
|
|
|
|
## Quickstart
|
|
|
|
<Admonition type="note">
|
|
|
|
Pick an install method and use the same tab in every step below. **Homebrew** gives you a global `supabase` command. **npm, pnpm, and yarn** install the CLI into your project as a dev dependency, so you run it through your package runner (`npx supabase`, `pnpm supabase`, or `yarn supabase`). See [Install and run the CLI](/docs/guides/local-development/cli/getting-started) for details.
|
|
|
|
</Admonition>
|
|
|
|
1. Install the Supabase CLI:
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="npm" queryGroup="package-manager"><TabPanel id="npm" label="npm">
|
|
|
|
```sh
|
|
npm install supabase --save-dev
|
|
```
|
|
|
|
</TabPanel><TabPanel id="yarn" label="yarn">
|
|
|
|
```sh
|
|
NODE_OPTIONS=--no-experimental-fetch yarn add supabase --dev
|
|
```
|
|
|
|
</TabPanel><TabPanel id="pnpm" label="pnpm">
|
|
|
|
```sh
|
|
pnpm add supabase --save-dev --allow-build=supabase
|
|
```
|
|
|
|
<Admonition type="note">
|
|
|
|
The `--allow-build=supabase` flag is required on pnpm version 10 or higher. If you're using an older version of pnpm, omit this flag.
|
|
|
|
</Admonition>
|
|
|
|
</TabPanel><TabPanel id="brew" label="brew">
|
|
|
|
```sh
|
|
brew install supabase/tap/supabase
|
|
```
|
|
|
|
</TabPanel></Tabs>
|
|
|
|
2. In your repo, initialize the local Supabase project:
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="npm" queryGroup="package-manager"><TabPanel id="npm" label="npm">
|
|
|
|
```sh
|
|
npx supabase init
|
|
```
|
|
|
|
</TabPanel><TabPanel id="yarn" label="yarn">
|
|
|
|
```sh
|
|
yarn supabase init
|
|
```
|
|
|
|
</TabPanel><TabPanel id="pnpm" label="pnpm">
|
|
|
|
```sh
|
|
pnpm supabase init
|
|
```
|
|
|
|
</TabPanel><TabPanel id="brew" label="brew">
|
|
|
|
```sh
|
|
supabase init
|
|
```
|
|
|
|
</TabPanel>
|
|
|
|
</Tabs>
|
|
|
|
3. Start the local Supabase stack:
|
|
|
|
<Tabs scrollable size="small" type="underlined" defaultActiveId="npm" queryGroup="package-manager"><TabPanel id="npm" label="npm">
|
|
|
|
```sh
|
|
npx supabase start
|
|
```
|
|
|
|
</TabPanel><TabPanel id="yarn" label="yarn">
|
|
|
|
```sh
|
|
yarn supabase start
|
|
```
|
|
|
|
</TabPanel><TabPanel id="pnpm" label="pnpm">
|
|
|
|
```sh
|
|
pnpm supabase start
|
|
```
|
|
|
|
</TabPanel><TabPanel id="brew" label="brew">
|
|
|
|
```sh
|
|
supabase start
|
|
```
|
|
|
|
</TabPanel>
|
|
|
|
</Tabs>
|
|
|
|
4. View your local Supabase instance at [http://localhost:54323](http://localhost:54323).
|
|
|
|
<Admonition type="caution">
|
|
|
|
If your local development machine is connected to an untrusted public network, you should create a separate Docker network and bind to 127.0.0.1 before starting the local development stack. This restricts network access to only your localhost machine.
|
|
|
|
```sh
|
|
docker network create -o 'com.docker.network.bridge.host_binding_ipv4=127.0.0.1' local-network
|
|
npx supabase start --network-id local-network
|
|
```
|
|
|
|
You should never expose your local development stack publicly.
|
|
|
|
</Admonition>
|
|
|
|
## Local development
|
|
|
|
Local development with Supabase allows you to work on your projects in a self-contained environment on your local machine. Working locally has several advantages:
|
|
|
|
1. Faster development: You can make changes and see results instantly without waiting for remote deployments.
|
|
2. Offline work: You can continue development even without an internet connection.
|
|
3. Cost-effective: Local development is free and doesn't consume your project's quota.
|
|
4. Enhanced privacy: Sensitive data remains on your local machine during development.
|
|
5. Safe testing: You can experiment with different configurations and features without affecting your production environment.
|
|
|
|
Once set up, you can initialize a new Supabase project, start the local stack, and begin developing your application using local Supabase services. This includes access to a local Postgres database, Auth, Storage, and other Supabase features.
|
|
|
|
With the default ports, `supabase start` runs one local project per machine. To run a local project for each app or git worktree at the same time, use the experimental `supabase stack` commands described in [Running multiple local projects](/docs/guides/local-development/running-multiple-local-projects).
|
|
|
|
## CLI
|
|
|
|
The Supabase CLI is a tool that enables developers to run Supabase services locally and manage hosted projects directly from the terminal. It provides a suite of commands for various tasks, including:
|
|
|
|
- Setting up and managing local development environments
|
|
- Generating TypeScript types for your database schema
|
|
- Handling [database migrations](/docs/guides/local-development/database-migrations) and [declarative database schemas](/docs/guides/local-development/declarative-database-schemas)
|
|
- Managing environment variables and secrets
|
|
- Deploying your project to the Supabase platform
|
|
|
|
With the CLI, you can streamline your development workflow, automate repetitive tasks, and maintain consistency across different environments. It's an essential tool for both local development and CI/CD pipelines.
|
|
|
|
See the [CLI Getting Started guide](/docs/guides/local-development/cli/getting-started) for more information.
|