A modern full-stack boilerplate featuring Next.js 15, Supabase, Shadcn/UI, and more. Built with TypeScript and includes authentication, dark mode, internationalization, and a todo list demo.
- Features
- Prerequisites
- Getting Started
- Project Structure
- Available Scripts
- Authentication
- Internationalization
- Customization
- Testing
- Good Practices
- Contributing
- License
- 🚀 Next.js 15 with App Router
- 🎨 Shadcn/UI components
- 📚 Storybook for component development
- 🔐 Supabase Authentication & Database
- 🌍 Internationalization with next-intl
- 🎭 Dark mode with next-themes
- 📝 Form handling with react-hook-form and zod
- 🔄 Data fetching with TanStack Query
- 🎯 TypeScript support
- 💅 Tailwind CSS for styling
- 🧪 Testing setup with Vitest and Cypress
- 📦 Lucide Icons
- Node.js 20+
- Docker (for local Supabase)
- Git
- Clone the repository:
git clone https://github.com/pierrecabriere/nss-boilerplate.git my-project
cd my-projectYou can also rename all the references to this boilerplate in the project.
- in
package.json - in
supabase/config.toml - in
src/app/layout.tsx
- Install dependencies:
npm install- Start local Supabase:
npx supabase startThis will start a local Supabase instance using Docker. Make note of the anon key and API URL that are displayed.
- Push database migrations:
npx supabase db push --localThis will create the initial database structure, including the todos table.
- Set environment variables:
cp .env.example .envUpdate the .env file with your Supabase credentials:
SUPABASE_URL: Usuallyhttp://127.0.0.1:54321SUPABASE_ANON_KEY: The anon key from step 3SUPABASE_BASE_KEY: Same as your anon key for local development
- Create a first user:
- Open Supabase Studio at
http://127.0.0.1:54323 - Go to Authentication > Users
- Create a new user with email/password
- Ensure the user has the
authenticatedrole
- Start the development server:
npm run devVisit http://localhost:3000 to see your application.
src/
├── app/ # Next.js app router pages
│ ├── auth/ # Authentication pages
│ └── ... # Other pages
├── components/ # React components
│ ├── ui/ # Shadcn/UI components
│ └── ... # Custom components
├── hooks/ # Custom React hooks
├── lib/ # Utility functions and configurations
│ ├── api/ # API related functions
│ └── supabase/ # Supabase client configurations
├── types/ # TypeScript type definitions
└── i18n/ # Internationalization
└── messages/ # Internationalization messages
├── stories/ # Storybook stories
│ ├── components/ # Component stories
│ └── pages/ # Page stories
supabase/
└── functions/ # Supabase Edge Functions (Deno)
If you're using VS Code, you can limit Deno's type checking to only the Supabase functions directory by adding this to your .vscode/settings.json:
{
"deno.enablePaths": ["supabase/functions"]
}This ensures that Deno only runs in the Supabase Edge Functions directory and doesn't interfere with the rest of your TypeScript setup.
npm run dev- Start development servernpm run build- Build for productionnpm run start- Start production servernpm run lint- Run ESLintnpm run test- Run Vitest testsnpm run cypress:open- Open Cypress test runnernpm run cypress:run- Run Cypress tests headlesslynpm run gen:types- Generate TypeScript types from Supabase schemanpm run storybook- Start Storybook development servernpm run build-storybook- Build Storybook for production
The boilerplate includes a complete authentication system using Supabase Auth:
- Email/Password authentication
- Protected routes using middleware
- User context and hooks
- Login/Logout functionality
Supports multiple languages out of the box:
- English and French included by default
- Easy to add more languages in
src/i18n/messages/directory and in theSUPPORTED_LANGUAGESarray insrc/components/settings-modal.tsx - Language switching with persistent selection in cookie
- Modify the theme in
src/app/globals.css - Dark mode support using
next-themes - Customizable Shadcn/UI components in
src/components/ui
Shadcn/UI offers a tool to customize your theme. You can find it at https://ui.shadcn.com/themes. Then, you can replace the generated theme in src/app/globals.css with your custom theme. Be careful to replace only the @layer base { ... } block.
- Generate updated types with
npm run gen:types
- Unit testing with Vitest
- E2E testing with Cypress
- Example tests included
To run the tests:
npm run test
npm run cypress:openThe project includes Storybook for component development and documentation:
- Stories are located in
src/stories/ - Component stories in
src/stories/components/ - Page stories in
src/stories/pages/
npm run storybookVisit http://localhost:6006 to see your component stories.
Create new stories in the src/stories directory following the pattern:
// Example: src/stories/components/button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from '@/components/ui/button';
const meta: Meta<typeof Button> = {
component: Button,
// ... configuration
};
export default meta;
type Story = StoryObj<typeof Button>;
export const Primary: Story = {
args: {
variant: 'default',
children: 'Button',
},
};To build a static version of Storybook:
npm run build-storybookThe output will be in the storybook-static directory.
- Use kebab-case for all file names (e.g.,
my-component.tsx,use-auth.ts) - Remove unused boilerplate files (e.g.,
lib/api/todos) when starting a new project - Create Supabase migrations whenever you make database changes:
Then commit these migrations with your changes
npx supabase db pull
- Don't use
process.envdirectly in your code. Instead, use the environment variables defined insrc/lib/env.ts
Contributions are welcome! Please feel free to submit a Pull Request.
This project is licensed under the MIT License - see the LICENSE file for details.