refactors the local dev section

This commit is contained in:
Copple
2023-08-01 22:12:30 +02:00
parent 316e43a4bc
commit d6bc450ef0
7 changed files with 368 additions and 272 deletions

View File

@@ -72,12 +72,6 @@ export const HOMEPAGE_MENU_ITEMS: HomepageMenuItems = [
href: '/guides/platform',
level: 'platform',
},
{
label: 'Resources',
icon: 'resources',
href: '/guides/resources',
level: 'resources',
},
{
label: 'Self-Hosting',
icon: 'self-hosting',
@@ -130,7 +124,25 @@ export const HOMEPAGE_MENU_ITEMS: HomepageMenuItems = [
community: true,
},
{
label: 'Tools',
label: 'Resources',
},
{
label: 'CLI Commands',
icon: 'reference-cli',
href: '/reference/cli/introduction',
level: 'reference_javascript',
},
{
label: 'Management API',
icon: 'reference-api',
href: '/reference/api/introduction',
level: 'reference_javascript',
},
{
label: 'Guides and Examples',
icon: 'resources',
href: '/guides/resources',
level: 'resources',
},
{
label: 'Integrations',
@@ -139,12 +151,6 @@ export const HOMEPAGE_MENU_ITEMS: HomepageMenuItems = [
href: 'https://supabase.com/partners/integrations',
level: 'integrations',
},
{
label: 'Management API',
icon: 'reference-api',
href: '/reference/api/introduction',
level: 'reference_javascript',
},
],
[
{
@@ -983,16 +989,30 @@ export const supabase_cli: NavMenuConstant = {
title: 'Local Dev / CLI',
url: '/guides/cli',
items: [
{ name: 'Getting started', url: '/guides/cli' },
{ name: 'Local Development', url: '/guides/cli/local-development' },
{ name: 'Managing environments', url: '/guides/cli/managing-environments' },
{ name: 'Overview', url: '/guides/cli' },
{
name: 'Managing config and secrets',
url: '/guides/cli/managing-config',
name: 'Using the CLI',
url: undefined,
items: [
{ name: 'Getting started', url: '/guides/cli/getting-started' },
{ name: 'CLI Configuration', url: '/guides/cli/config' },
],
},
{
name: 'Testing emails locally',
url: '/guides/cli/testing-emails',
name: 'Developing with Supabase',
url: undefined,
items: [
{ name: 'Local Development', url: '/guides/cli/local-development' },
{ name: 'Managing environments', url: '/guides/cli/managing-environments' },
{
name: 'Managing config and secrets',
url: '/guides/cli/managing-config',
},
{
name: 'Testing emails locally',
url: '/guides/cli/testing-emails',
},
],
},
{
name: 'GitHub Action',
@@ -1004,14 +1024,6 @@ export const supabase_cli: NavMenuConstant = {
},
],
},
{
name: 'Reference',
url: undefined,
items: [
{ name: 'Commands', url: '/reference/cli/introduction' },
{ name: 'Configuration', url: '/reference/cli/config' },
],
},
],
}

View File

@@ -1,162 +1,47 @@
import Layout from '~/layouts/DefaultGuideLayout'
export const meta = {
title: 'Supabase CLI',
description:
'The Supabase CLI provides tools to develop your project locally and deploy to the Supabase Platform.',
subtitle:
'The Supabase CLI provides tools to develop your project locally and deploy to the Supabase Platform.',
id: 'cli',
title: 'Local Dev / CLI',
description: 'Developing locally using the Supabase CLI.',
subtitle: 'Developing locally using the Supabase CLI.',
sidebar_label: 'Overview',
}
You can use the Supabase CLI to run the entire Supabase stack locally on your machine, simply by running `supabase init` (to create a new local project) and then `supabase start`.
You can use the Supabase CLI to run the entire Supabase stack locally on your machine, simply by running `supabase init` and then `supabase start`.
The Supabase CLI provides tools to develop your project locally, deploy to the Supabase Platform, handle database migrations, and generate types directly from your database schema.
## Installing the Supabase CLI
## Resources
<Tabs
scrollable
size="small"
type="underlined"
defaultActiveId="npm"
>
<TabPanel id="npm" label="npm">
<div className="grid md:grid-cols-12 gap-4 not-prose">
{integrations.map((x) => (
<div className="col-span-6" key={x.href}>
<Link href={x.href} passHref>
<a>
<GlassPanel icon={'/docs/img/icons/github-icon'} hasLightIcon={true} title={x.name}>
{x.description}
</GlassPanel>
</a>
</Link>
</div>
))}
</div>
Install the CLI as dev dependency via [npm](https://www.npmjs.com/package/supabase):
export const integrations = [
{
name: 'Supabase CLI',
description:
'The Supabase CLI provides tools to develop manage your Supabase projects from your local machine.',
href: 'https://github.com/supabase/cli',
},
{
name: 'GitHub Action',
description: ' A GitHub action for interacting with your Supabase projects using the CLI.',
href: 'https://github.com/supabase/setup-cli',
},
]
```sh
npm install supabase --save-dev
```
Run the CLI by prefixing each command with `npx` (only applicable when installing through `npm`):
```sh
npx supabase <command>
```
</TabPanel>
<TabPanel id="macos" label="macOS">
Install the CLI with [Homebrew](https://brew.sh):
```sh
brew install supabase/tap/supabase
```
</TabPanel>
<TabPanel id="windows" label="Windows">
Install the CLI with [Scoop](https://scoop.sh):
```powershell
scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
scoop install supabase
```
</TabPanel>
<TabPanel id="linux" label="Linux">
The CLI is available through [Homebrew](https://brew.sh) and Linux packages.
#### Homebrew
```sh
brew install supabase/tap/supabase
```
#### Linux packages
Linux packages are provided in [Releases](https://github.com/supabase/cli/releases).
To install, download the `.apk`/`.deb`/`.rpm` file depending on your package manager
and run one of the following:
- `sudo apk add --allow-untrusted <...>.apk`
- `sudo dpkg -i <...>.deb`
- `sudo rpm -i <...>.rpm`
</TabPanel>
</Tabs>
## Updating the Supabase CLI
When a new [version](https://github.com/supabase/cli/releases) is released, you can update the CLI using the same methods.
<Tabs
scrollable
size="small"
type="underlined"
defaultActiveId="npm"
>
<TabPanel id="npm" label="npm">
```sh
npm update supabase --save-dev
```
</TabPanel>
<TabPanel id="macos" label="macOS">
```sh
brew upgrade supabase
```
</TabPanel>
<TabPanel id="windows" label="Windows">
```powershell
scoop update supabase
```
</TabPanel>
<TabPanel id="linux" label="Linux">
```sh
brew upgrade supabase
```
</TabPanel>
</Tabs>
If you have any Supabase containers running locally, remember to restart them after upgrading to use the new features.
```bash
npx supabase stop --no-backup
npx supabase start
```
## Running Supabase locally
Inside the folder where you want to create your project, run:
```bash
supabase init
```
This will create a new `supabase` folder. It's safe to commit this folder to your version control system.
Now, to start the Supabase stack, run:
```bash
supabase start
```
This takes time on your first run because the CLI needs to download the local Docker images. The CLI includes the entire Supabase toolset, and a few additional images that are useful for local development (like a local SMTP server and a database diff tool).
The local development environment includes Supabase Studio, a graphical interface for working with your database, running by default on [localhost:54323](http://localhost:54323).
![Local Studio](/docs/img/guides/cli/local-studio.png)
When you are finished working on your Supabase project, you can stop the stack with:
```bash
supabase stop
```
## See also
- [Supabase CLI Reference](/docs/reference/cli/introduction)
- [Supabase CLI Configuration](/docs/reference/cli/config)
export const Page = ({ children }) => <Layout meta={meta} children={children} />
export const Page = ({ children }) => <Layout meta={meta} children={children} hideToc={true} />
export default Page

View File

@@ -0,0 +1,113 @@
import specFile from '~/../../spec/cli_v1_config.yaml' assert { type: 'yml' }
import { Parameter } from '~/lib/refGenerator/refTypes'
import ReactMarkdown from 'react-markdown'
import GuidesTableOfContents from '~/components/GuidesTableOfContents'
import { Heading } from '~/components/CustomHTMLElements'
import Head from 'next/head'
import { CodeBlock } from 'ui'
// Parameters are grouped on the page by tag
const TAGS = ['General', 'Auth', 'API', 'Database', 'Dashboard', 'Local', 'Edge-Functions']
const tocList = []
const content = TAGS.map((tag) => {
tocList.push({ text: tag, link: `${tag.toLowerCase()}-config`, level: 2 })
return (
<div>
<Heading tag="h2">{tag} Config</Heading>
{specFile.parameters
.filter((param: Parameter) => param.tags[0] === tag.toLowerCase())
.map((parameter: Parameter, index) => {
tocList.push({ text: parameter.id, link: `#${parameter.id}`, level: 3 })
return <Info parameter={parameter} />
})}
</div>
)
})
export default function Config() {
return (
<>
<Head>
<title>Supabase CLI config</title>
</Head>
<div className="grid grid-cols-12 relative gap-4 px-5 max-w-7xl mx-auto py-16">
<div className="relative col-span-12 md:col-span-9 transition-all ease-out duration-100">
<div className="w-full prose">
<h1 className="">CLI configuration</h1>
<div className="max-w-xs w-32 h-[1px] bg-gradient-to-r from-brand-800 to-brand-900 my-8"></div>
<ReactMarkdown>{specFile.info.description}</ReactMarkdown>
<div>{content}</div>
</div>
</div>
<div className="md:col-span-3">
<div className="sticky top-20 border-l">
<span className="block font-mono text-xs uppercase text-scale-1200 pl-5 mb-4">
On this page
</span>
<GuidesTableOfContents list={tocList} />
</div>
</div>
</div>
</>
)
}
function Info({ parameter }: { parameter: Parameter }) {
return (
<div className="mt-8">
<div>
<Heading tag="h3" parseAnchors={false} customAnchor={parameter.id}>
<code>{parameter.title}</code>
</Heading>
<div className="border-b pb-8" key={parameter.id}>
<div className=" mb-16">
<div className="">
<table className="table-auto">
<thead>
<tr>
<th className="text-left">Name</th>
<th className="text-left">Default</th>
<th className="text-left">Required</th>
</tr>
</thead>
<tbody>
<tr>
<td>{parameter.id}</td>
<td>{parameter.default ? parameter.default.toString() : 'None'}</td>
<td>{parameter.required.toString()}</td>
</tr>
</tbody>
</table>
</div>
<div className="mb-4 scroll-mt-16 mt-0 ">
<p className="text-sm font-bold uppercase">Description</p>
<ReactMarkdown>{parameter.description}</ReactMarkdown>
</div>
{parameter.usage && (
<div className="mb-4 scroll-mt-16 mt-0 ">
<p className="text-sm font-bold uppercase">Usage</p>
<CodeBlock className="useless-code-block-class" language="py">
{parameter.usage}
</CodeBlock>
</div>
)}
{parameter.links && (
<div>
<p className="text-sm font-bold uppercase">See also</p>
<ul>
{parameter.links.map((link) => (
<li>
<a href={link.link}>{link.name}</a>
</li>
))}
</ul>
</div>
)}
</div>
</div>
</div>
</div>
)
}

View File

@@ -0,0 +1,172 @@
import Layout from '~/layouts/DefaultGuideLayout'
export const meta = {
title: 'Supabase CLI',
description:
'The Supabase CLI provides tools to develop your project locally and deploy to the Supabase Platform.',
subtitle:
'The Supabase CLI provides tools to develop your project locally and deploy to the Supabase Platform.',
}
You can use the Supabase CLI to run the entire Supabase stack locally on your machine, simply by running `supabase init` (to create a new local project) and then `supabase start`.
The Supabase CLI provides tools to develop your project locally, deploy to the Supabase Platform, handle database migrations, and generate types directly from your database schema.
## Installing the Supabase CLI
<Tabs
scrollable
size="small"
type="underlined"
defaultActiveId="npm"
>
<TabPanel id="npm" label="npm">
Install the CLI as dev dependency via [npm](https://www.npmjs.com/package/supabase):
```sh
npm install supabase --save-dev
```
Run the CLI by prefixing each command with `npx` (only applicable when installing through `npm`):
```sh
npx supabase <command>
```
</TabPanel>
<TabPanel id="macos" label="macOS">
Install the CLI with [Homebrew](https://brew.sh):
```sh
brew install supabase/tap/supabase
```
</TabPanel>
<TabPanel id="windows" label="Windows">
Install the CLI with [Scoop](https://scoop.sh):
```powershell
scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
scoop install supabase
```
</TabPanel>
<TabPanel id="linux" label="Linux">
The CLI is available through [Homebrew](https://brew.sh) and Linux packages.
#### Homebrew
```sh
brew install supabase/tap/supabase
```
#### Linux packages
Linux packages are provided in [Releases](https://github.com/supabase/cli/releases).
To install, download the `.apk`/`.deb`/`.rpm` file depending on your package manager
and run one of the following:
- `sudo apk add --allow-untrusted <...>.apk`
- `sudo dpkg -i <...>.deb`
- `sudo rpm -i <...>.rpm`
</TabPanel>
</Tabs>
## Updating the Supabase CLI
When a new [version](https://github.com/supabase/cli/releases) is released, you can update the CLI using the same methods.
<Tabs
scrollable
size="small"
type="underlined"
defaultActiveId="npm"
>
<TabPanel id="npm" label="npm">
```sh
npm update supabase --save-dev
```
</TabPanel>
<TabPanel id="macos" label="macOS">
```sh
brew upgrade supabase
```
</TabPanel>
<TabPanel id="windows" label="Windows">
```powershell
scoop update supabase
```
</TabPanel>
<TabPanel id="linux" label="Linux">
```sh
brew upgrade supabase
```
</TabPanel>
</Tabs>
If you have any Supabase containers running locally, remember to restart them after upgrading to use the new features.
```bash
npx supabase stop --no-backup
npx supabase start
```
## Running Supabase locally
Inside the folder where you want to create your project, run:
```bash
supabase init
```
This will create a new `supabase` folder. It's safe to commit this folder to your version control system.
Now, to start the Supabase stack, run:
```bash
supabase start
```
This takes time on your first run because the CLI needs to download the local Docker images. The CLI includes the entire Supabase toolset, and a few additional images that are useful for local development (like a local SMTP server and a database diff tool).
The local development environment includes Supabase Studio, a graphical interface for working with your database, running by default on [localhost:54323](http://localhost:54323).
![Local Studio](/docs/img/guides/cli/local-studio.png)
## Stopping local services
When you are finished working on your Supabase project, you can stop the stack with:
```bash
supabase stop
```
## Full command reference
The CLI provides a number of commands to help you develop your project locally and deploy to the Supabase Platform. You can find all commands inside the [CLI Reference](/docs/reference/cli/introduction) docs, including:
- [Project](/docs/reference/cli/supabase-projects) and [Organization](/docs/reference/cli/supabase-orgs) management
- [Database management](/docs/reference/cli/supabase-db)
- [Database migrations](/docs/reference/cli/supabase-migration) and [Database Branching](/docs/reference/cli/supabase-branches)
- [Database debugigng tools](/docs/reference/cli/supabase-inspect-db-calls)
- [Edge Function management](/docs/reference/cli/supabase-functions)
- [Auth management](/docs/reference/cli/supabase-functions)
- [Types Generators](/docs/reference/cli/supabase-gen)
- [Testing](/docs/reference/cli/supabase-test)
export const Page = ({ children }) => <Layout meta={meta} children={children} />
export default Page

View File

@@ -1,94 +0,0 @@
import specFile from '~/../../spec/cli_v1_config.yaml' assert { type: 'yml' }
import { Parameter } from '~/lib/refGenerator/refTypes'
import ReactMarkdown from 'react-markdown'
import GuidesTableOfContents from '~/components/GuidesTableOfContents'
import { Heading } from '~/components/CustomHTMLElements'
import Head from 'next/head'
// Parameters are grouped on the page by tag
const TAGS = ['general', 'auth', 'api', 'database', 'dashboard', 'local', 'edge-functions']
const tocList = TAGS.map((tag) =>
specFile.parameters
.filter((param: Parameter) => param.tags[0] === tag)
.map((parameter) => {
const text = parameter.id
const link = `#${parameter.id}`
const level = '2'
return { text, link, level }
})
).flat()
export default function Config() {
return (
<>
<Head>
<title>Supabase CLI config</title>
</Head>
<div className="grid grid-cols-12 relative gap-4 px-5 max-w-7xl mx-auto py-16">
<div className="relative col-span-12 md:col-span-9 transition-all ease-out duration-100">
<div className="w-full prose">
<h1 className="">CLI configuration</h1>
<div className="max-w-xs w-32 h-[1px] bg-gradient-to-r from-brand-800 to-brand-900 my-8"></div>
<ReactMarkdown>{specFile.info.description}</ReactMarkdown>
<div>
{TAGS.map((tag) =>
specFile.parameters
.filter((param: Parameter) => param.tags[0] === tag)
.map((parameter: Parameter, index) => (
<div>
{index === 0 && <h2 className="text-xl capitalize">{tag}</h2>}
<div className="mt-8">
<div>
<Heading tag="h2" parseAnchors={false} customAnchor={parameter.id}>
<code>{parameter.title}</code>
</Heading>
<div className="grid">
<div className="border-b pb-8" key={parameter.id}>
<div className=" mb-16">
<p className="mb-4 scroll-mt-16 mt-0 text-scale-1100 text-base">
<ReactMarkdown>{parameter.description}</ReactMarkdown>
</p>
<div className="grid gap-2">
<div className="flex gap-2">
Required: <code>{parameter.required.toString()}</code>
</div>
<div className="flex gap-2">
Default:
<code>
{parameter.default ? parameter.default.toString() : 'None'}
</code>
</div>
</div>
</div>
{parameter.links &&
parameter.links.map((link) => (
<div>
<h3>See also:</h3>
<li>
<a href={link.link}>{link.name}</a>
</li>
</div>
))}
</div>
</div>
</div>
</div>
</div>
))
)}
</div>
</div>
</div>
<div className="md:col-span-3">
<div className="sticky top-20 border-l">
<span className="block font-mono text-xs uppercase text-scale-1200 pl-5 mb-4">
On this page
</span>
<GuidesTableOfContents list={tocList} />
</div>
</div>
</div>
</>
)
}

View File

@@ -2246,4 +2246,9 @@ module.exports = [
source: '/docs/guides/integrations/zuplo',
destination: '/partners/integrations/zuplo',
},
{
permanent: true,
source: '/docs/reference/cli/config',
destination: '/docs/guides/cli/config',
},
]

View File

@@ -15,7 +15,7 @@ info:
description: |
A `config.toml` file is generated after running `supabase init`.
This file is located in the `supabase` folder under `supabase/config.toml`.
This file is located in the `supabase` folder under `supabase/config.toml`. You can edit this file to change the settings for your locally running project. After you make changes, you will need to restart using `supabase stop` and then `supabase start` for the changes to take effect.
tags:
- id: general
title: General
@@ -57,6 +57,9 @@ parameters:
links:
- name: 'PostgREST configuration'
link: 'https://postgrest.org/en/stable/configuration.html'
usage: |
[api]
port = 54321
- id: 'api.schemas'
title: 'api.schemas'