From d6bc450ef0faab75b89856ca89da153f7aed3b2d Mon Sep 17 00:00:00 2001 From: Copple <10214025+kiwicopple@users.noreply.github.com> Date: Tue, 1 Aug 2023 22:12:30 +0200 Subject: [PATCH] refactors the local dev section --- .../NavigationMenu.constants.ts | 68 ++++--- apps/docs/pages/guides/cli.mdx | 183 ++++-------------- apps/docs/pages/guides/cli/config.tsx | 113 +++++++++++ .../docs/pages/guides/cli/getting-started.mdx | 172 ++++++++++++++++ apps/docs/pages/reference/cli/config.tsx | 94 --------- apps/www/lib/redirects.js | 5 + spec/cli_v1_config.yaml | 5 +- 7 files changed, 368 insertions(+), 272 deletions(-) create mode 100644 apps/docs/pages/guides/cli/config.tsx create mode 100644 apps/docs/pages/guides/cli/getting-started.mdx delete mode 100644 apps/docs/pages/reference/cli/config.tsx diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts index 71029382f99..749a91645ae 100644 --- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts +++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts @@ -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' }, - ], - }, ], } diff --git a/apps/docs/pages/guides/cli.mdx b/apps/docs/pages/guides/cli.mdx index 38506dd1df0..6527974049f 100644 --- a/apps/docs/pages/guides/cli.mdx +++ b/apps/docs/pages/guides/cli.mdx @@ -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 - - +
+ {integrations.map((x) => ( +
+ + + + {x.description} + + + +
+ ))} +
-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 -``` - - - - -Install the CLI with [Homebrew](https://brew.sh): - -```sh -brew install supabase/tap/supabase -``` - - - - -Install the CLI with [Scoop](https://scoop.sh): - -```powershell -scoop bucket add supabase https://github.com/supabase/scoop-bucket.git -scoop install supabase -``` - - - - -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` - - - - -## 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. - - - - -```sh -npm update supabase --save-dev -``` - - - - -```sh -brew upgrade supabase -``` - - - - -```powershell -scoop update supabase -``` - - - - -```sh -brew upgrade supabase -``` - - - - -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 }) => +export const Page = ({ children }) => export default Page diff --git a/apps/docs/pages/guides/cli/config.tsx b/apps/docs/pages/guides/cli/config.tsx new file mode 100644 index 00000000000..97a928e2bb6 --- /dev/null +++ b/apps/docs/pages/guides/cli/config.tsx @@ -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 ( +
+ {tag} Config + {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 + })} +
+ ) +}) + +export default function Config() { + return ( + <> + + Supabase CLI config + +
+
+
+

CLI configuration

+
+ {specFile.info.description} +
{content}
+
+
+
+
+ + On this page + + +
+
+
+ + ) +} + +function Info({ parameter }: { parameter: Parameter }) { + return ( +
+
+ + {parameter.title} + + +
+
+
+ + + + + + + + + + + + + + + +
NameDefaultRequired
{parameter.id}{parameter.default ? parameter.default.toString() : 'None'}{parameter.required.toString()}
+
+
+

Description

+ {parameter.description} +
+ {parameter.usage && ( +
+

Usage

+ + {parameter.usage} + +
+ )} + {parameter.links && ( +
+

See also

+
    + {parameter.links.map((link) => ( +
  • + {link.name} +
    • + ))} +
+
+ )} +
+
+
+
+ ) +} diff --git a/apps/docs/pages/guides/cli/getting-started.mdx b/apps/docs/pages/guides/cli/getting-started.mdx new file mode 100644 index 00000000000..dd01d4ffcf7 --- /dev/null +++ b/apps/docs/pages/guides/cli/getting-started.mdx @@ -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 + + + + +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 +``` + + + + +Install the CLI with [Homebrew](https://brew.sh): + +```sh +brew install supabase/tap/supabase +``` + + + + +Install the CLI with [Scoop](https://scoop.sh): + +```powershell +scoop bucket add supabase https://github.com/supabase/scoop-bucket.git +scoop install supabase +``` + + + + +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` + + + + +## 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. + + + + +```sh +npm update supabase --save-dev +``` + + + + +```sh +brew upgrade supabase +``` + + + + +```powershell +scoop update supabase +``` + + + + +```sh +brew upgrade supabase +``` + + + + +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 }) => + +export default Page diff --git a/apps/docs/pages/reference/cli/config.tsx b/apps/docs/pages/reference/cli/config.tsx deleted file mode 100644 index 096aa30b6aa..00000000000 --- a/apps/docs/pages/reference/cli/config.tsx +++ /dev/null @@ -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 ( - <> - - Supabase CLI config - -
-
-
-

CLI configuration

-
- {specFile.info.description} -
- {TAGS.map((tag) => - specFile.parameters - .filter((param: Parameter) => param.tags[0] === tag) - .map((parameter: Parameter, index) => ( -
- {index === 0 &&

{tag}

} -
-
- - {parameter.title} - -
-
-
-

- {parameter.description} -

-
-
- Required: {parameter.required.toString()} -
-
- Default: - - {parameter.default ? parameter.default.toString() : 'None'} - -
-
-
- {parameter.links && - parameter.links.map((link) => ( -
-

See also:

-
  • - {link.name} -
    • -
    - ))} -
    -
    -
    -
    -
    - )) - )} -
    -
    -
    -
    -
    - - On this page - - -
    -
    -
    - - ) -} diff --git a/apps/www/lib/redirects.js b/apps/www/lib/redirects.js index 3bac4663636..09080de1ecd 100644 --- a/apps/www/lib/redirects.js +++ b/apps/www/lib/redirects.js @@ -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', + }, ] diff --git a/spec/cli_v1_config.yaml b/spec/cli_v1_config.yaml index 09b38779278..308a3e0c4ae 100644 --- a/spec/cli_v1_config.yaml +++ b/spec/cli_v1_config.yaml @@ -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'