mirror of
https://github.com/supabase/supabase.git
synced 2026-10-05 09:25:06 +03:00
feat(library): add starter app guides (#50368)
## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Feature, docs. Part 2 of 6 in a stack that splits the library redesign into reviewable pieces. ## What is the current behavior? The library documents individual blocks. Nothing answers "I have no project yet" — a reader who wants a working app has to assemble one from block guides and figure out the scaffolding themselves. ## What is the new behavior? Four starter guides under `/docs/starters`, each starting from an empty directory and ending with a running app on Supabase: - **Next.js starter** — composes the library's own password-based auth block. - **SaaS starter** — the community subscription-payments template, with Stripe setup. - **AI chat app** — the community Vercel AI SDK template. - **Flutter starter** — the user-management example, with profiles and avatar uploads. They reuse the existing doc route, so the sidebar, command menu, Markdown export and `llms.txt` pick them up with no new plumbing. The framework selector already renders nothing for pages that declare no framework variants, so a starter page shows none. ## Additional context The starter pages are added here in the current site's page layout; the last PR in the stack converts them to the new one along with every other guide. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **New Features** - Added a Starter Apps section to the side navigation and command menu. - Added links for Next.js, SaaS, AI Chat, and Flutter starter projects, marked as new. - **Documentation** - Added setup and deployment guides for the Next.js and SaaS starters. - Added an AI Chat App guide covering configuration, local verification, and deployment. - Added a Flutter starter guide covering authentication, profiles, avatars, deep links, and hosted setup. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Saxon FletcherandClaude Opus 5 authored and GitHub committed
1 parent
7fd37e6150
commit
b1d2efd99e
6 files changed
+297
No files matched your search
@@ -9,6 +9,7 @@ import {
|
||||
mcpBlocks,
|
||||
oauthBlocks,
|
||||
platformBlocks,
|
||||
starterApps,
|
||||
} from '@/config/docs'
|
||||
|
||||
function SideNavigation() {
|
||||
@@ -80,6 +81,14 @@ function SideNavigation() {
|
||||
<NavigationItem item={item} key={`${item.href}-${i}`} />
|
||||
))}
|
||||
</div>
|
||||
<div className="pb-6 space-y-0.5">
|
||||
<div className="font-mono uppercase text-xs text-foreground-lighter/75 mb-2 px-6 tracking-widest">
|
||||
{starterApps.title}
|
||||
</div>
|
||||
{starterApps.items.map((item, i) => (
|
||||
<NavigationItem item={item} key={`${item.href}-${i}`} />
|
||||
))}
|
||||
</div>
|
||||
<div className="pb-6">
|
||||
<div className="font-mono uppercase text-xs text-foreground-lighter/75 mb-2 px-6 tracking-widest">
|
||||
UI Blocks
|
||||
|
||||
@@ -24,6 +24,40 @@ export const gettingStarted: SidebarNavGroup = {
|
||||
],
|
||||
}
|
||||
|
||||
export const starterApps: SidebarNavGroup = {
|
||||
title: 'Starter Apps',
|
||||
items: [
|
||||
{
|
||||
title: 'Next.js Starter',
|
||||
href: '/docs/starters/nextjs-starter',
|
||||
items: [],
|
||||
new: true,
|
||||
commandItemLabel: 'Next.js Starter',
|
||||
},
|
||||
{
|
||||
title: 'SaaS Starter',
|
||||
href: '/docs/starters/saas-starter',
|
||||
items: [],
|
||||
new: true,
|
||||
commandItemLabel: 'SaaS Starter',
|
||||
},
|
||||
{
|
||||
title: 'AI Chat App',
|
||||
href: '/docs/starters/ai-chat-app',
|
||||
items: [],
|
||||
new: true,
|
||||
commandItemLabel: 'AI Chat App',
|
||||
},
|
||||
{
|
||||
title: 'Flutter Starter',
|
||||
href: '/docs/starters/flutter-starter',
|
||||
items: [],
|
||||
new: true,
|
||||
commandItemLabel: 'Flutter Starter',
|
||||
},
|
||||
],
|
||||
}
|
||||
|
||||
export const platformBlocks: SidebarNavGroup = {
|
||||
title: 'Platform',
|
||||
items: [
|
||||
@@ -164,6 +198,10 @@ export const COMMAND_ITEMS = [
|
||||
label: item.commandItemLabel,
|
||||
href: item.href,
|
||||
})),
|
||||
...starterApps.items.map((item) => ({
|
||||
label: item.commandItemLabel,
|
||||
href: item.href,
|
||||
})),
|
||||
...componentPages.items.map((item) => ({
|
||||
label: item.commandItemLabel,
|
||||
href: item.href,
|
||||
|
||||
@@ -0,0 +1,57 @@
|
||||
---
|
||||
title: AI Chat App
|
||||
description: >-
|
||||
A Next.js chat app with streaming responses, authentication, and saved
|
||||
conversations
|
||||
---
|
||||
|
||||
The [Supabase Community AI chatbot template](https://github.com/supabase-community/vercel-ai-chatbot) includes a chat interface, streaming responses, Supabase Auth, and conversation history in Postgres. Creating the app installs those features together.
|
||||
|
||||
## Installation
|
||||
|
||||
### Create the app
|
||||
|
||||
Scaffold the template with the [Next.js CLI](https://nextjs.org/docs/app/api-reference/cli/create-next-app):
|
||||
|
||||
```bash
|
||||
npx create-next-app@latest my-chat --example https://github.com/supabase-community/vercel-ai-chatbot --use-pnpm
|
||||
cd my-chat
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
This community template uses Next.js 13, AI SDK 2, and Supabase Auth Helpers. Review its [dependency versions](https://github.com/supabase-community/vercel-ai-chatbot/blob/main/package.json) and plan upgrades before deployment. For a new authentication foundation using `@supabase/ssr`, start with the [Next.js starter](/library/docs/starters/nextjs-starter).
|
||||
|
||||
## Start Supabase
|
||||
|
||||
Install [Docker](https://docs.docker.com/get-started/get-docker/) and the [Supabase CLI](https://supabase.com/docs/guides/local-development/cli/getting-started), then run the local stack from the template directory:
|
||||
|
||||
```bash
|
||||
supabase start
|
||||
```
|
||||
|
||||
The template includes database migrations for chat history. Use the project URL and `anon` key printed by the CLI in `.env`:
|
||||
|
||||
```env
|
||||
NEXT_PUBLIC_SUPABASE_URL=your-local-api-url
|
||||
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-local-anon-key
|
||||
OPENAI_API_KEY=your-model-provider-api-key
|
||||
NEXT_PUBLIC_AUTH_GITHUB=false
|
||||
```
|
||||
|
||||
The variable names match the template's [environment example](https://github.com/supabase-community/vercel-ai-chatbot/blob/main/.env.example). Keep `OPENAI_API_KEY` on the server. To add GitHub sign-in, follow the template's [OAuth setup](https://github.com/supabase-community/vercel-ai-chatbot#set-up-github-oauth) and fill in its provider settings.
|
||||
|
||||
## Choose a model
|
||||
|
||||
The template selects its model in [`app/api/chat/route.ts`](https://github.com/supabase-community/vercel-ai-chatbot/blob/main/app/api/chat/route.ts). Replace the example model with one available to your provider account that supports the template's Chat Completions streaming API. Keep the model selection and API key in the server route.
|
||||
|
||||
## Run the app
|
||||
|
||||
```bash
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
Open [the app](http://localhost:3000), sign up, and send a message. Use the local email inbox URL printed by the Supabase CLI to confirm your account. Confirm that the response streams and that the conversation appears in your history after refreshing.
|
||||
|
||||
## Deploy the app
|
||||
|
||||
Follow the template's [deployment guide](https://github.com/supabase-community/vercel-ai-chatbot#deploy-your-own) to connect a hosted Supabase project, apply its migrations, and set the production Auth Site URL and server environment variables.
|
||||
@@ -0,0 +1,70 @@
|
||||
---
|
||||
title: Flutter Starter
|
||||
description: 'A Flutter user management app with magic links, profiles, and avatar uploads'
|
||||
---
|
||||
|
||||
Start from the [Supabase Flutter user management example](https://github.com/supabase/supabase/tree/master/examples/user-management/flutter-user-management). It includes a Flutter app, the Supabase Flutter SDK, account screens, and local database migrations.
|
||||
|
||||
## Installation
|
||||
|
||||
### Create the app
|
||||
|
||||
Install the [Flutter SDK](https://docs.flutter.dev/get-started/install), then copy the example with a sparse Git checkout:
|
||||
|
||||
```bash
|
||||
git clone --depth 1 --filter=blob:none --sparse https://github.com/supabase/supabase.git my-flutter-app
|
||||
cd my-flutter-app
|
||||
git sparse-checkout set examples/user-management/flutter-user-management
|
||||
cd examples/user-management/flutter-user-management
|
||||
```
|
||||
|
||||
This checks out the complete Flutter project, including its Android, iOS, and web configuration. Flutter uses the example's Dart widgets and SDK dependencies directly.
|
||||
|
||||
### Install dependencies
|
||||
|
||||
```bash
|
||||
flutter pub get
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
## Configure Supabase
|
||||
|
||||
Install [Docker](https://docs.docker.com/get-started/get-docker/) and the [Supabase CLI](https://supabase.com/docs/guides/local-development/cli/getting-started), then start the example's database and migrations:
|
||||
|
||||
```bash
|
||||
supabase start
|
||||
```
|
||||
|
||||
Fill in `.env` with the local API URL and publishable key printed by the CLI:
|
||||
|
||||
```env
|
||||
SUPABASE_URL=your-local-api-url
|
||||
SUPABASE_PUBLISHABLE_KEY=your-publishable-key
|
||||
```
|
||||
|
||||
Update the initialization in `lib/main.dart` to read the same variable name as `.env.example`:
|
||||
|
||||
```dart
|
||||
await Supabase.initialize(
|
||||
url: dotenv.env['SUPABASE_URL']!,
|
||||
anonKey: dotenv.env['SUPABASE_PUBLISHABLE_KEY']!,
|
||||
);
|
||||
```
|
||||
|
||||
The SDK's `anonKey` argument accepts a publishable key. The example's original `SUPABASE_ANON_KEY` lookup must match the name you use in `.env`.
|
||||
|
||||
## Run the app
|
||||
|
||||
Start with the web target to use the local Supabase instance:
|
||||
|
||||
```bash
|
||||
flutter run -d web-server --web-hostname localhost --web-port 3000
|
||||
```
|
||||
|
||||
Open [the app](http://localhost:3000), request a magic link, and open the local email inbox printed by the Supabase CLI. Sign in, edit your profile, and upload an avatar.
|
||||
|
||||
For Android or iOS, run `flutter run` and configure [mobile deep links](https://supabase.com/docs/guides/auth/native-mobile-deep-linking) for `io.supabase.flutterquickstart://login-callback/`. Use a Supabase URL reachable from your simulator or device.
|
||||
|
||||
## Use a hosted project
|
||||
|
||||
Follow the [Flutter user management tutorial](https://supabase.com/docs/guides/getting-started/tutorials/with-flutter) to set up the profile table, Storage policies, and authentication URLs in your Supabase project. Replace the local values in `.env` with that project's URL and publishable key.
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: Next.js Starter
|
||||
description: 'A Next.js app with Supabase authentication, TypeScript, and Tailwind CSS'
|
||||
---
|
||||
|
||||
Start with a Next.js App Router project, then install the Library's password-based authentication block. The block adds sign-in, sign-up, password recovery, and a protected page.
|
||||
|
||||
## Installation
|
||||
|
||||
### Create the app
|
||||
|
||||
Use the [shadcn CLI](https://ui.shadcn.com/docs/cli#init) to create a Next.js app with Tailwind CSS and Radix-based components:
|
||||
|
||||
```bash
|
||||
npx shadcn@latest init --template next --base radix --name my-app
|
||||
cd my-app
|
||||
```
|
||||
|
||||
### Install the block
|
||||
|
||||
Run the install command from your new project:
|
||||
|
||||
<BlockItem name="password-based-auth-nextjs" showOpenInV0={false} />
|
||||
|
||||
The installer adds the Supabase client and authentication routes. Keep the generated package lockfile with your project.
|
||||
|
||||
## Configure Supabase
|
||||
|
||||
Create a [Supabase project](https://supabase.com/dashboard/new), then add its URL and publishable key to `.env.local`:
|
||||
|
||||
```env
|
||||
NEXT_PUBLIC_SUPABASE_URL=your-project-url
|
||||
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=your-publishable-key
|
||||
```
|
||||
|
||||
Find these values in your project's [Connect dialog](https://supabase.com/dashboard/project/_?showConnect=true&connectTab=frameworks&framework=nextjs).
|
||||
|
||||
Set the Auth Site URL to `http://localhost:3000` in [URL configuration](https://supabase.com/dashboard/project/_/auth/url-configuration). Follow the [authentication block's email template and redirect setup](/library/docs/nextjs/password-based-auth#adding-email-templates) to enable email confirmation and password recovery. Set the generated forms' post-authentication destination to `/protected`.
|
||||
|
||||
## Run the app
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Open [the sign-up page](http://localhost:3000/auth/sign-up), create an account, and follow the confirmation email to the protected page.
|
||||
|
||||
## Add more blocks
|
||||
|
||||
- [Social Auth](/library/docs/nextjs/social-auth) adds OAuth sign-in providers.
|
||||
- [Current User Avatar](/library/docs/nextjs/current-user-avatar) displays the signed-in user's profile.
|
||||
- [Dropzone](/library/docs/nextjs/dropzone) adds file uploads.
|
||||
|
||||
Built with [Next.js](https://nextjs.org/) and the [Supabase password-based authentication block](https://github.com/supabase/supabase/tree/master/apps/ui-library/registry/default/blocks/password-based-auth-nextjs).
|
||||
@@ -0,0 +1,69 @@
|
||||
---
|
||||
title: SaaS Starter
|
||||
description: A Next.js subscription app with Supabase Auth and Stripe billing
|
||||
---
|
||||
|
||||
The [Supabase Community subscription template](https://github.com/supabase-community/nextjs-subscription-payments) includes authentication, subscription checkout, a customer portal, and database migrations. Its components and billing routes are installed together when you create the app.
|
||||
|
||||
## Installation
|
||||
|
||||
### Create the app
|
||||
|
||||
Scaffold the complete template with the [Next.js CLI](https://nextjs.org/docs/app/api-reference/cli/create-next-app):
|
||||
|
||||
```bash
|
||||
npx create-next-app@latest my-saas --example https://github.com/supabase-community/nextjs-subscription-payments --use-pnpm
|
||||
cd my-saas
|
||||
```
|
||||
|
||||
The scaffold uses the template's dependency versions and includes its authentication implementation. Review dependency updates before deploying your app.
|
||||
|
||||
## Start Supabase
|
||||
|
||||
Install [Docker](https://docs.docker.com/get-started/get-docker/) and the [Supabase CLI](https://supabase.com/docs/guides/local-development/cli/getting-started). Copy the template's environment files, then start its local database and migrations:
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
cp .env.local.example .env.local
|
||||
pnpm supabase:start
|
||||
```
|
||||
|
||||
Use the values printed by `pnpm supabase:status` to fill in `.env.local`:
|
||||
|
||||
```env
|
||||
NEXT_PUBLIC_SUPABASE_URL=your-local-api-url
|
||||
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-local-anon-key
|
||||
SUPABASE_SERVICE_ROLE_KEY=your-local-service-role-key
|
||||
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=your-stripe-test-publishable-key
|
||||
STRIPE_SECRET_KEY=your-stripe-test-secret-key
|
||||
STRIPE_WEBHOOK_SECRET=your-local-webhook-signing-secret
|
||||
```
|
||||
|
||||
These names match the template. Keep `SUPABASE_SERVICE_ROLE_KEY`, `STRIPE_SECRET_KEY`, and `STRIPE_WEBHOOK_SECRET` in server environment variables.
|
||||
|
||||
## Connect Stripe
|
||||
|
||||
Install the [Stripe CLI](https://docs.stripe.com/stripe-cli), sign in, and keep webhook forwarding running in a separate terminal:
|
||||
|
||||
```bash
|
||||
pnpm stripe:login
|
||||
pnpm stripe:listen
|
||||
```
|
||||
|
||||
Copy the listener's signing secret into `STRIPE_WEBHOOK_SECRET`. Start the app in another terminal:
|
||||
|
||||
```bash
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
Load the template's sample test products after the app and webhook listener are running:
|
||||
|
||||
```bash
|
||||
pnpm stripe:fixtures
|
||||
```
|
||||
|
||||
Open [the app](http://localhost:3000), create an account, and test a subscription. Configure the [Stripe customer portal](https://dashboard.stripe.com/test/settings/billing/portal) to let customers change or cancel their plans.
|
||||
|
||||
## Deploy the app
|
||||
|
||||
Follow the template's [deployment setup](https://github.com/supabase-community/nextjs-subscription-payments#step-by-step-setup) for the hosted database, Auth URLs, production Stripe keys, and webhook endpoint. The template's [package scripts](https://github.com/supabase-community/nextjs-subscription-payments/blob/main/package.json) cover local migrations and billing fixtures.
|
||||
Reference in new issue
Block a user