From bc0977f492b8f9cce94f4e8b95db87ece76ffa20 Mon Sep 17 00:00:00 2001 From: Terry Sutton Date: Tue, 25 Mar 2025 11:30:13 -0230 Subject: [PATCH] UI library/docs (#34377) * Add faq sections * Update the faq. * Minor updates to the client and auth guides. * Add missing pages to the sidebar. * Rename the React category to React SPA. --------- Co-authored-by: Ivan Vasilov --- apps/ui-library/config/docs.ts | 14 +++- .../content/docs/getting-started/faq.mdx | 79 +++++++++++++------ .../docs/getting-started/introduction.mdx | 34 ++++++-- .../ui-library/content/docs/nextjs/client.mdx | 5 +- .../docs/nextjs/password-based-auth.mdx | 2 + .../content/docs/react-router/client.mdx | 3 + apps/ui-library/content/docs/react/client.mdx | 6 +- .../docs/react/password-based-auth.mdx | 4 +- .../content/docs/tanstack/client.mdx | 3 + 9 files changed, 112 insertions(+), 38 deletions(-) diff --git a/apps/ui-library/config/docs.ts b/apps/ui-library/config/docs.ts index 722620c80f6..aa5c375e313 100644 --- a/apps/ui-library/config/docs.ts +++ b/apps/ui-library/config/docs.ts @@ -74,6 +74,12 @@ export const frameworkPages: Record = { 'react-router': { title: 'React Router', items: [ + { + title: 'Client', + href: '/docs/react-router/client', + items: [], + commandItemLabel: 'Supabase Client for React Router', + }, { title: 'Dropzone', href: '/docs/react-router/dropzone', @@ -118,8 +124,14 @@ export const frameworkPages: Record = { ], }, react: { - title: 'React', + title: 'React SPA', items: [ + { + title: 'Client', + href: '/docs/react/client', + items: [], + commandItemLabel: 'Supabase Client for React SPA', + }, { title: 'Password-Based Auth', href: '/docs/react/password-based-auth', diff --git a/apps/ui-library/content/docs/getting-started/faq.mdx b/apps/ui-library/content/docs/getting-started/faq.mdx index c30faa146c1..b4c7ade3b97 100644 --- a/apps/ui-library/content/docs/getting-started/faq.mdx +++ b/apps/ui-library/content/docs/getting-started/faq.mdx @@ -3,32 +3,59 @@ title: FAQ description: Frequently asked questions --- - - - Will it overwrite what I already have? - Answer + + + How does it work? + + You run a command in a new or existing project that looks something like this: + ```bash + npx shadcn@latest add http://supabase.com/ui/r/password-based-auth-nextjs.json + ``` + This will add all of the files to your project and install the dependencies. + After you've run the command, you can start using the components. In the case of Auth, you should be up and running with user sign in/sign up with just this one command. + + + Will it overwrite my existing files? + + No. If you run a command in an existing project, it will not overwrite your existing + files. If there conflicting files, you will be asked what you want to do (leave them or + overwrite them). If you run it in a new project, it will just add the new files to your project. + + + + I've already started my a project, what should I do? + + You can still use these components, even if you've already started your project! The commands + won't overwrite your existing files, but you should still be careful with the changes to makes + sure you understand what's been added. You should commit your changes into Git before running + these commands so you'll be able to see a clean diff of the changes. + + + + I've already installed shadcn/ui, what should I do? + + You're off to a great start! You can now run an add command to add the desired component to your + project. + + + + + I already started with `npx create-next-app -e with-supabase` what should I do now? + + + Our Next.js quickstart is a great starting point for building a full app with Supabase and + Next.js. If you've already started with this template, you can use add command to add more + components to your project. + + + + I used an AI builder to build my app, what should I do? + + If your app is already built, you can use any of the commands to drop components into your + project. Your app likely already has a Supabase client set up, so you can just continue using + that if it's working well for you. + + - - I've already installed shadcn/ui, what should I do? - Answer - - - - I already started with -e with-supabase what should I do? - - Answer - - - I use pages router - Answer - - - I use app router - Answer - - - I use none of the things mentioned, what can I do? - Answer - diff --git a/apps/ui-library/content/docs/getting-started/introduction.mdx b/apps/ui-library/content/docs/getting-started/introduction.mdx index f71f9b25bcf..69c40b4c2cf 100644 --- a/apps/ui-library/content/docs/getting-started/introduction.mdx +++ b/apps/ui-library/content/docs/getting-started/introduction.mdx @@ -1,10 +1,34 @@ --- title: Introduction -description: Components +description: A flexible, open-source UI component library built on shadcn/ui, designed to simplify Supabase-powered projects with pre-built Auth, Storage, and Realtime features. --- -## Code Block +Our Supabase UI component library is a set of components built on top of the shadcn/ui registry system. It's designed to make building new or existing Supabase-powered projects faster and easier by providing pre-built solutions for common but challenging features—such as authentication, file uploads, and real-time updates. -```js -console.log('Hello World') -``` +Our Supabase UI library aims to solve these issues with: + +- **Extensible components**: Modify and extend simple primitives as needed. + +- **Composable Components**: Modular structure that makes components easy to integrate and combine. + +- **Supabase Clients**: Interact with Supabase however you choose. + +- **Scaffolding for Hard Problems**: Pre-built solutions for challenging features like sign-in/sign-up flows, file uploads, and real-time data sync. + +- **New or existing projects**: Designed to work with brand new projects or to fit easily into existing ones. + +### Extensible components + +Our components are designed to be easily extensible. You can modify the code to fit your needs and use it as a starting point for your own components. You can change any of the code to fit your needs and use it as a starting point for your own components. The important part is that the code is designed to make the hard parts easy, and leave the easy parts for you. + +### Composable components + +Our components are designed to be easily composable. You can combine them to create new components that are tailored to your needs. If you want to change the design or behavior of a component, you can easily do so in your own codebase. + +### Supabase Clients + +The Supabase Clients are the backbone of your apps. They are designed to be easily integrated with your existing Supabase project. We provide both client-side and server-side clients for several major frameworks, and the code is designed to be easily integrated with your existing codebase. + +### Scaffolding for Hard Problems + +Setting up something like Auth should be easy, so we've done the hard work for you. Our components are designed to be easily integrated with your new or existing Supabase projects. Installing them drops the files into place so you can get the hard parts out of the way quickly. diff --git a/apps/ui-library/content/docs/nextjs/client.mdx b/apps/ui-library/content/docs/nextjs/client.mdx index cb5b0cd8e67..0d5b914818f 100644 --- a/apps/ui-library/content/docs/nextjs/client.mdx +++ b/apps/ui-library/content/docs/nextjs/client.mdx @@ -15,7 +15,7 @@ description: Supabase client for Next.js This block installs a Supabase client to be used by Next.js. It's meant to be used with app router and it's fully SSR compatible. -If you started a project through `npx create-next-app -e with-supabase` command, this block is already included in your project. +If you already have your Supabase client(s) set up and working well (through the through `npx create-next-app -e with-supabase` template or in another way) you can just continue using them. To get started, you need to add an `.env` file to your project with the following entries: @@ -27,3 +27,6 @@ NEXT_PUBLIC_SUPABASE_ANON_KEY= If you're using a local instance of supabase, you can find these values by running `supabase start` or `supabase status` (if already running). If you're using supabase.com project, you can find them in the [Connect modal](https://supabase.com/dashboard/project/_?showConnect=true) under App Frameworks or in your project's [API settings](https://supabase.com/dashboard/project/_/settings/api). + +This block provides Supabase clients designed for use with SSR by storing JWT tokens in cookies. If you're +developing a React SPA, use the [React SPA client](/ui/docs/react-router/client) instead. diff --git a/apps/ui-library/content/docs/nextjs/password-based-auth.mdx b/apps/ui-library/content/docs/nextjs/password-based-auth.mdx index 4268e622cc2..4284410e099 100644 --- a/apps/ui-library/content/docs/nextjs/password-based-auth.mdx +++ b/apps/ui-library/content/docs/nextjs/password-based-auth.mdx @@ -42,3 +42,5 @@ To finish the installation: 1. Set the site URL in the [Supabase Dashboard](https://supabase.com/dashboard/project/_/auth/url-configuration). 1. Set the `forgot-password` route in `forgot-password-form.tsx` component. The same route also needs to be configured as a redirect URL in the [Supabase Dashboard](https://supabase.com/dashboard/project/_/auth/url-configuration). It should look something like this: `http://example.com/auth/forgot-password`. 1. Update the redirect paths in the `login-form.tsx` and `update-password-form.tsx` components to point to the logged-in routes in your app. + +You can use this block with pages router by simply moving the routes from the `app` folder into the `pages` folder and renaming them. diff --git a/apps/ui-library/content/docs/react-router/client.mdx b/apps/ui-library/content/docs/react-router/client.mdx index e7c94c44c14..214297dd5e2 100644 --- a/apps/ui-library/content/docs/react-router/client.mdx +++ b/apps/ui-library/content/docs/react-router/client.mdx @@ -10,3 +10,6 @@ description: Supabase client for React Router ## Folder structure + +This block provides Supabase clients designed for use with SSR by storing JWT tokens in cookies. If you're +developing a React SPA, use the [React SPA client](/ui/docs/react-router/client) instead. diff --git a/apps/ui-library/content/docs/react/client.mdx b/apps/ui-library/content/docs/react/client.mdx index 411abab3e2c..2aa3af05b15 100644 --- a/apps/ui-library/content/docs/react/client.mdx +++ b/apps/ui-library/content/docs/react/client.mdx @@ -1,11 +1,11 @@ --- -title: React -description: Supabase client for React +title: React Single Page Applications +description: Supabase client for React Single Page Applications --- ## Installation - + ## Folder structure diff --git a/apps/ui-library/content/docs/react/password-based-auth.mdx b/apps/ui-library/content/docs/react/password-based-auth.mdx index f4abcebf05d..d39f7a45e17 100644 --- a/apps/ui-library/content/docs/react/password-based-auth.mdx +++ b/apps/ui-library/content/docs/react/password-based-auth.mdx @@ -1,6 +1,6 @@ --- -title: Password-based Auth (React) -description: Password-based Auth block for React +title: Password-based Authentication +description: Password-based authentication block for React Single Page Applications --- ## Installation diff --git a/apps/ui-library/content/docs/tanstack/client.mdx b/apps/ui-library/content/docs/tanstack/client.mdx index 15c5d31b544..7ab51bba1fb 100644 --- a/apps/ui-library/content/docs/tanstack/client.mdx +++ b/apps/ui-library/content/docs/tanstack/client.mdx @@ -16,3 +16,6 @@ The easiest way to use Tanstack Start with Supabase is to follow the following s ## Folder structure + +This block provides Supabase clients designed for use with SSR by storing JWT tokens in cookies. If you're +developing a React SPA, use the [React SPA client](/ui/docs/react-router/client) instead.