The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
feat(library): add starter app guides (#50368)
Saxon Fletcherb1d2efd99e4b
diff --git a/apps/ui-library/components/side-navigation.tsx b/apps/ui-library/components/side-navigation.tsxindex d24ee10c70f..44dfae11c7a 100644--- a/apps/ui-library/components/side-navigation.tsx+++ b/apps/ui-library/components/side-navigation.tsx@@ -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 Blocksdiff --git a/apps/ui-library/config/docs.ts b/apps/ui-library/config/docs.tsindex e91b532d833..83c350797fb 100644--- a/apps/ui-library/config/docs.ts+++ b/apps/ui-library/config/docs.ts@@ -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,diff --git a/apps/ui-library/content/docs/starters/ai-chat-app.mdx b/apps/ui-library/content/docs/starters/ai-chat-app.mdxnew file mode 100644index 00000000000..0018d172ee7--- /dev/null+++ b/apps/ui-library/content/docs/starters/ai-chat-app.mdx@@ -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.diff --git a/apps/ui-library/content/docs/starters/flutter-starter.mdx b/apps/ui-library/content/docs/starters/flutter-starter.mdxnew file mode 100644index 00000000000..81ee662f249--- /dev/null+++ b/apps/ui-library/content/docs/starters/flutter-starter.mdx@@ -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.diff --git a/apps/ui-library/content/docs/starters/nextjs-starter.mdx b/apps/ui-library/content/docs/starters/nextjs-starter.mdxnew file mode 100644index 00000000000..d689ff6bc5c--- /dev/null+++ b/apps/ui-library/content/docs/starters/nextjs-starter.mdx@@ -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).diff --git a/apps/ui-library/content/docs/starters/saas-starter.mdx b/apps/ui-library/content/docs/starters/saas-starter.mdxnew file mode 100644index 00000000000..92682a01f34--- /dev/null+++ b/apps/ui-library/content/docs/starters/saas-starter.mdx@@ -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.