diff --git a/apps/docs/app/page.tsx b/apps/docs/app/page.tsx index f6d2be258b8..c042353d68f 100644 --- a/apps/docs/app/page.tsx +++ b/apps/docs/app/page.tsx @@ -148,6 +148,12 @@ const clientLibraries = [ ] const additionalResources = [ + { + title: 'Interactive Walkthrough', + description: 'A step-by-step guide to building with Supabase.', + icon: 'compass', + href: '/walkthrough', + }, { title: 'Management API', description: 'Manage your Supabase projects and organizations.', diff --git a/apps/docs/app/walkthrough/client-page.tsx b/apps/docs/app/walkthrough/client-page.tsx new file mode 100644 index 00000000000..4708712e081 --- /dev/null +++ b/apps/docs/app/walkthrough/client-page.tsx @@ -0,0 +1,448 @@ +'use client' + +import { useRouter } from 'next/navigation' +import Link from 'next/link' +import { useState } from 'react' +import { + Button, + ToggleGroup, + ToggleGroupItem, + Card, + CardHeader, + CardTitle, + CardContent, + Checkbox_Shadcn_, +} from 'ui' +import { IconPanel } from 'ui-patterns/IconPanel' +import { useBreakpoint } from 'common' +import { + Tabs_Shadcn_ as Tabs, + TabsContent_Shadcn_ as TabsContent, + TabsList_Shadcn_ as TabsList, + TabsTrigger_Shadcn_ as TabsTrigger, +} from 'ui' +import { cn } from 'ui' +import { Code, MousePointerClick, Check } from 'lucide-react' + +const steps = [ + { id: 'step1', title: '1. Choose Workflow' }, + { id: 'step2', title: '2. Create a Project' }, + { id: 'step3', title: '3. Modify Schema' }, + { id: 'step4', title: '4. Configure Auth' }, + { id: 'step5', title: '5. Connect to App' }, + { id: 'step6', title: '6. Go to Production' }, + { id: 'step7', title: '7. Branching' }, +] + +type Workflow = 'code-first' | 'no-code' + +interface WalkthroughClientPageProps { + codeFirstSchemaContent: React.ReactNode + noCodeSchemaContent: React.ReactNode + codeFirstAuthConfig: React.ReactNode + noCodeAuthConfig: React.ReactNode + connectToAppContent: React.ReactNode + createProjectContent: React.ReactNode + codeFirstBranchingContent: React.ReactNode + noCodeBranchingContent: React.ReactNode +} + +const checklistItems = [ + { + id: 'security', + title: 'Security', + description: + 'Enable RLS on tables, configure SSL and Network Restrictions, and use MFA to protect your account. Use the Security Advisor to find issues.', + }, + { + id: 'performance', + title: 'Performance', + description: + 'Add database indexes, perform load testing, and upgrade your database if needed. Use the Performance Advisor for suggestions.', + }, + { + id: 'availability', + title: 'Availability', + description: + 'Use a custom SMTP server for auth emails. For critical applications, upgrade to a paid plan and configure PITR and Read Replicas.', + }, + { + id: 'rate-limiting', + title: 'Rate Limiting and Abuse Prevention', + description: 'Be aware of rate limits. Use CAPTCHA on auth endpoints to prevent abuse.', + }, + { + id: 'status-page', + title: 'Subscribe to Status Page', + description: 'Stay informed about Supabase service status by subscribing to the status page.', + }, +] + +const ProductionChecklist = () => { + const [checkedState, setCheckedState] = useState>({}) + + const handleCheckedChange = (id: string, checked: boolean) => { + setCheckedState((prev) => ({ ...prev, [id]: checked })) + } + + return ( +
+

Getting Ready for Production

+

+ Here are the final steps to get your application ready for production users. This is a + summary of our{' '} + + Production Checklist + + . +

+ + + Production Checklist + + +
    + {checklistItems.map((item, index) => ( +
  • + handleCheckedChange(item.id, !!checked)} + className="mt-1" + /> +
    + +

    {item.description}

    +
    +
    • + ))} +
+ + +
+ ) +} + +export function WalkthroughClientPage({ + codeFirstSchemaContent, + noCodeSchemaContent, + codeFirstAuthConfig, + noCodeAuthConfig, + connectToAppContent, + createProjectContent, + codeFirstBranchingContent, + noCodeBranchingContent, +}: WalkthroughClientPageProps) { + const router = useRouter() + const [workflow, setWorkflow] = useState('code-first') + const [currentStep, setCurrentStep] = useState(steps[0].id) + + const handleNext = () => { + const currentIndex = steps.findIndex((s) => s.id === currentStep) + if (currentIndex === steps.length - 1) { + router.push('/docs') + } else if (currentIndex < steps.length - 1) { + setCurrentStep(steps[currentIndex + 1].id) + } + } + + const handleBack = () => { + const currentIndex = steps.findIndex((s) => s.id === currentStep) + if (currentIndex > 0) { + setCurrentStep(steps[currentIndex - 1].id) + } + } + + const Step1 = ( +
+

Choose Your Preferred Workflow

+

+ Supabase can be used in a code-first or no-code approach. When your needs change you can + transition between the two. +

+ { + setWorkflow(value ? (value as Workflow) : null) + }} + className="grid grid-cols-1 md:grid-cols-2 gap-4" + > + + +

Code-first

+

+ Your schema, functions and configuration are defined in code. +

+ + + +

No-code

+

+ Use the Supabase Dashboard to manage your database, functions and project configuration +

+ + + {workflow && ( + + + Ideal for + + + {workflow === 'code-first' ? ( +
    +
  • + + Complex applications with custom business logic. +
    • +
  • + + Teams that use Git for version control and CI/CD. +
    • +
  • + + Automated testing and deployment pipelines. +
    • +
  • + + Projects that require fine-grained control over the database schema. +
    • +
+ ) : ( +
    +
  • + + Rapid prototyping and MVPs. +
    • +
  • + + Internal tools and dashboards. +
    • +
  • + + Simple applications with standard features. +
    • +
  • + + Developers who prefer a visual interface for speed. +
    • +
+ )} + + + )} +
+ ) + + const Step2 =
{createProjectContent}
+ + const Step3 = ( +
+

Modifying Your Database Schema

+ {!workflow ? ( +

Please select a workflow in Step 1.

+ ) : workflow === 'code-first' ? ( + codeFirstSchemaContent + ) : ( + noCodeSchemaContent + )} +
+ ) + + const Step4 = ( +
+

Configure Authentication

+ {!workflow ? ( +

Please select a workflow in Step 1.

+ ) : workflow === 'code-first' ? ( + codeFirstAuthConfig + ) : ( + noCodeAuthConfig + )} +
+ ) + + const frameworks = [ + { + tooltip: 'ReactJS', + icon: '/docs/img/icons/react-icon', + href: '/guides/getting-started/quickstarts/reactjs', + }, + { + tooltip: 'Next.js', + icon: '/docs/img/icons/nextjs-icon', + href: '/guides/getting-started/quickstarts/nextjs', + }, + { + tooltip: 'RedwoodJS', + icon: '/docs/img/icons/redwoodjs-icon', + href: '/guides/getting-started/quickstarts/redwoodjs', + }, + { + tooltip: 'Flutter', + icon: '/docs/img/icons/flutter-icon', + href: '/guides/getting-started/quickstarts/flutter', + }, + { + tooltip: 'Android Kotlin', + icon: '/docs/img/icons/kotlin-icon', + href: '/guides/getting-started/quickstarts/kotlin', + }, + { + tooltip: 'SvelteKit', + icon: '/docs/img/icons/svelte-icon', + href: '/guides/getting-started/quickstarts/sveltekit', + }, + { + tooltip: 'SolidJS', + icon: '/docs/img/icons/solidjs-icon', + href: '/guides/getting-started/quickstarts/solidjs', + }, + { + tooltip: 'Vue', + icon: '/docs/img/icons/vuejs-icon', + href: '/guides/getting-started/quickstarts/vue', + }, + { + tooltip: 'Nuxt', + icon: '/docs/img/icons/nuxt-icon', + href: '/guides/getting-started/quickstarts/nuxtjs', + }, + { + tooltip: 'refine', + icon: '/docs/img/icons/refine-icon', + href: '/guides/getting-started/quickstarts/refine', + }, + ] + const [selectedFramework, setSelectedFramework] = useState('Next.js') + const isXs = useBreakpoint(639) + const iconSize = isXs ? 'sm' : 'lg' + + const Step5 = ( +
+

Connecting to Your App

+

+ We have a quickstart for each of the following frameworks. +

+
+ {frameworks.map((f) => ( + + ))} +
+ {selectedFramework && connectToAppContent} +
+ ) + + const Step6 = + + const Step7 = ( +
+

Branching

+ {!workflow ? ( +

Please select a workflow in Step 1.

+ ) : workflow === 'code-first' ? ( +
{codeFirstBranchingContent}
+ ) : ( +
{noCodeBranchingContent}
+ )} +
+ ) + + const currentIndex = steps.findIndex((s) => s.id === currentStep) + + return ( +
+ {workflow && ( + { + if (value) setWorkflow(value as Workflow) + }} + > + + + + + + + + )} + +
+
+ {Step1} + {Step2} + {Step3} + {Step4} + {Step5} + {Step6} + {Step7} +
+ + +
+
+
+ + + {steps.map((step) => ( + + {step.title} + + ))} + + +
+ ) +} diff --git a/apps/docs/app/walkthrough/page.tsx b/apps/docs/app/walkthrough/page.tsx new file mode 100644 index 00000000000..fd5c2475504 --- /dev/null +++ b/apps/docs/app/walkthrough/page.tsx @@ -0,0 +1,26 @@ +import { + CodeFirstSchemaContent, + NoCodeSchemaContent, + CodeFirstAuthConfig, + NoCodeAuthConfig, + ConnectToAppContent, + CreateProjectContent, + CodeFirstBranchingContent, + NoCodeBranchingContent, +} from './step-content' +import { WalkthroughClientPage } from './client-page' + +export default function WalkthroughsPage() { + return ( + } + noCodeSchemaContent={} + codeFirstAuthConfig={} + noCodeAuthConfig={} + connectToAppContent={} + createProjectContent={} + codeFirstBranchingContent={} + noCodeBranchingContent={} + /> + ) +} diff --git a/apps/docs/app/walkthrough/step-content.tsx b/apps/docs/app/walkthrough/step-content.tsx new file mode 100644 index 00000000000..4fc0be97d25 --- /dev/null +++ b/apps/docs/app/walkthrough/step-content.tsx @@ -0,0 +1,443 @@ +import { Card, CardHeader, CardTitle } from 'ui' +import { CodeBlock } from '~/features/ui/CodeBlock/CodeBlock' +import { Edit, Terminal, Sparkles, Users, AtSign, Github } from 'lucide-react' +import { Image } from 'ui' +import StepHikeCompact from '~/components/StepHikeCompact' + +export async function CodeFirstSchemaContent() { + return ( +
+

+ Use a declarative schema file to define your database structure. The Supabase CLI compares + this to your database state to generate migration files. +

+ + + +

+ Create or edit a SQL file in the supabase/schemas directory to define + your tables, views, and functions. +

+ + + + + + + +

+ This command creates a new migration file with the SQL needed to update your database. +

+ + + `} /> + + + + +

+ Apply the migrations to your production database. +

+ + + + + + +
+ ) +} + +export function CreateProjectContent() { + return ( +
+

Create a new Supabase project

+

+ Before you can start building, you need to create a project in the Supabase Dashboard. +

+ + + +

+ Navigate to{' '} + + app.supabase.com + {' '} + to get started. +

+ + + + +

+ Click on "New project" and choose the organization you want to create the project in. +

+ + + + +

+ Provide a name for your project, generate a secure database password, and choose the + region closest to your users. +

+ + + +
+ ) +} + +export async function CodeFirstAuthConfig() { + return ( +
+

+ Manage your authentication settings by defining them in your{' '} + supabase/config.toml file. This allows you to keep your auth configuration in + version control. +

+ + + +

+ Set your application's site URL and any additional redirect URLs. This is crucial for + security and ensures that users are redirected to the correct location after + authentication. +

+ + + + + + + +

+ You can enable or disable new user sign-ups. For many applications, you might want to + disable sign-ups after an initial period. +

+ + + + + + + +

+ Enable social providers like GitHub by adding their configuration. You'll need to get + the client ID and secret from the provider's developer console. +

+ + + + + + +
+ ) +} + +export function NoCodeSchemaContent() { + return ( +
+

+ The Dashboard provides several ways to modify your database schema +

+
+ + Diagram showing the state transitions of a signing key +
+ +
+

Table Editor

+

+ Visually create, edit, and delete tables and columns. This is the easiest way to get + started and manage your database for most use cases. +

+
+
+ + + Diagram showing the state transitions of a signing key +
+ +
+

AI Assistant

+

+ Use the AI Assistant to generate SQL from natural language prompts. Describe what + you want to do, and the AI will generate the SQL for you to review and run. +

+
+
+ + + Diagram showing the state transitions of a signing key +
+ +
+

SQL Editor

+

+ For more complex needs, use the SQL Editor to run any SQL command. You can create + views, functions, and advanced policies. You can also save your favorite queries as + snippets. +

+
+
+ +
+
+ ) +} + +export function NoCodeAuthConfig() { + return ( +
+

+ Configure authentication using the Supabase Dashboard. Navigate to the Authentication + section in the sidebar to get started. +

+
+ + +
+

Enable user sign-ups

+

+ In the Providers section, you can enable or disable sign-ups for different methods, + like email and password, or phone-based login. +

+
+ + + +
+

Set up email provider

+

+ In the Settings section, configure your SMTP settings to customize the emails sent to + your users for confirmations, password resets, and more. +

+
+ + + +
+

Configure Social Providers

+

+ In the Providers section, you can easily enable social logins like Google, GitHub, and + more. Simply toggle the provider and add your Client ID and Secret. +

+
+ +
+
+ ) +} + +export async function ConnectToAppContent() { + return ( +
+ + + +

+ The quickest way to get started is with the `with-supabase` template, which + pre-configures Cookie-based Auth, TypeScript, and Tailwind CSS. +

+ + + + + + + + +

+ Rename `.env.example` to `.env.local` and add your project's URL and anon key. You can + find these in your project's API settings. +

+ + + + + + + + +

+ The template includes a full authentication flow. Start the app and navigate to the + login page to sign up. +

+ + + + + + + + +

+ Once your app is set up, you can use the Supabase client to interact with your + database. Here's how you can fetch data inside a React Server Component. +

+ + + {JSON.stringify(employees, null, 2)} +}`} + /> + + + +
+ ) +} + +export function CodeFirstBranchingContent() { + return ( +
+

+ After launching your app, make follow-up changes—like schema or function updates—in a + branch. This lets you safely test and review updates before they reach production. In a + code-first workflow, connecting your Supabase project to GitHub enables automatic preview + branches for pull requests, so you can validate migrations and deployments before merging. +

+
    +
  1. +

    Connect to a GitHub repository

    +

    + In your project's settings, navigate to the Integrations page and connect your Supabase + project to a GitHub repository. This will allow Supabase to sync branches and run checks + on your pull requests. +

    +
    2. +
  2. +

    Enable automatic branching

    +

    + In the GitHub integration settings, enable "Automatic branching". Now, when you create a + new branch and push it to GitHub, a corresponding preview branch will be created on + Supabase. +

    +
    3. +
  3. +

    Deploy to production

    +

    + Enable the "Deploy to production" option in the integration settings. When you merge a + pull request into your main branch, the changes will be automatically deployed to your + production project. +

    +
    4. +
  4. +

    Enable required checks

    +

    + In your GitHub repository settings, make the Supabase integration a "required check". + This prevents merging pull requests that have failing migrations, keeping your + production database safe. +

    +
    5. +
+
+ ) +} + +export function NoCodeBranchingContent() { + return ( +
+

+ Once your app is live, any follow-up changes—like editing tables or adding new + features—should ideally be made in a branch. In a no-code workflow, you can create and + manage branches directly from the Supabase Dashboard, allowing you to safely test and review + updates before merging them into production. This approach is especially useful for quick + testing and prototyping without needing a Git repository. +

+
    +
  1. +

    Enable Branching 2.0

    +

    + Branching 2.0 is currently in public alpha. You can enable it from the Feature Preview + section in your user menu. +

    +
    2. +
  2. +

    Create a new branch

    +

    + From the branch selector in the top menu bar of the Dashboard, you can create a new + preview branch. +

    +
    3. +
  3. +

    Make changes to your branch

    +

    + Using the branch selector, switch to your new branch. Any changes you make with the + Table Editor, SQL Editor, or other dashboard tools will only apply to the preview + branch. +

    +
    4. +
  4. +

    Merge changes to production

    +

    + When you're ready, create a merge request from the dashboard. This will allow you to + review your changes and merge them into your production project. +

    +
    5. +
+
+ ) +} diff --git a/apps/docs/public/img/walkthrough/schema-ai.webp b/apps/docs/public/img/walkthrough/schema-ai.webp new file mode 100644 index 00000000000..a7e4bc7ba56 Binary files /dev/null and b/apps/docs/public/img/walkthrough/schema-ai.webp differ diff --git a/apps/docs/public/img/walkthrough/schema-sql.webp b/apps/docs/public/img/walkthrough/schema-sql.webp new file mode 100644 index 00000000000..8b917ca5bcf Binary files /dev/null and b/apps/docs/public/img/walkthrough/schema-sql.webp differ diff --git a/apps/docs/public/img/walkthrough/schema-table.webp b/apps/docs/public/img/walkthrough/schema-table.webp new file mode 100644 index 00000000000..488bb923674 Binary files /dev/null and b/apps/docs/public/img/walkthrough/schema-table.webp differ