Afoodi NSS

Table of Contents

• Features
• Prerequisites
• Getting Started
• Project Structure
• Available Scripts
• Authentication
• Internationalization
• Customization
• Testing
• Good Practices
• Contributing
• License

Features

• 🚀 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

Prerequisites

• Node.js 20+
• Docker (for local Supabase)
• Git

Getting Started

1. Clone the repository:

git clone git@github.com:tractr/afoodi-nss.git
cd afoodi-nss

2. Install dependencies:

npm install

3. Start local Supabase:

npx supabase start

This will start a local Supabase instance using Docker. Make note of the anon key and API URL that are displayed.

4. Push database migrations:

npx supabase db push --local

This will create the initial database structure, including the todos table.

5. Set environment variables:

cp .env.example .env

Update the .env file with your Supabase credentials:

• SUPABASE_URL: Usually http://127.0.0.1:54321
• SUPABASE_ANON_KEY: The anon key from step 3
• SUPABASE_BASE_KEY: Same as your anon key for local development

6. 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 authenticated role

7. Start the development server:

npm run dev

Visit http://localhost:3000 to see your application.

Project Structure

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

Available Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm run start - Start production server
• npm run lint - Run ESLint
• npm run test - Run Vitest tests
• npm run cypress:open - Open Cypress test runner
• npm run cypress:run - Run Cypress tests headlessly
• npm run gen:types - Generate TypeScript types from Supabase schema
• npm run storybook - Start Storybook development server
• npm run build-storybook - Build Storybook for production

Authentication

The boilerplate includes a complete authentication system using Supabase Auth:

• Email/Password authentication
• Protected routes using middleware
• User context and hooks
• Login/Logout functionality

Internationalization

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 the SUPPORTED_LANGUAGES array in src/components/settings-modal.tsx
• Language switching with persistent selection in cookie

Customization

Theme

• 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.

Database Schema

• Generate updated types with npm run gen:types

Testing

• Unit testing with Vitest
• E2E testing with Cypress
• Example tests included

To run the tests:

npm run test
npm run cypress:open

Storybook

The project includes Storybook for component development and documentation:

Structure

• Stories are located in src/stories/
• Component stories in src/stories/components/
• Page stories in src/stories/pages/

Running Storybook

npm run storybook

Visit http://localhost:6006 to see your component stories.

Writing 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',
  },
};

Building Storybook

To build a static version of Storybook:

npm run build-storybook

The output will be in the storybook-static directory.

Good Practices

• 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:

  npx supabase db pull

  Then commit these migrations with your changes
• Don't use process.env directly in your code. Instead, use the environment variables defined in src/lib/env.ts

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.