Developer Installation Guide

This guide covers setting up AniDojo locally for development, testing, and contributions.

This guide is for developers who want to contribute to AniDojo. End users should use the deployed web application.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js 18+

Required for running Next.js and development tools.Download from nodejs.org

Package Manager

Choose one:

npm (comes with Node.js)
yarn
pnpm
bun

Git

For cloning the repository and version control.

Supabase Account

Free account at supabase.com for backend services.

Installation Steps

Clone the Repository

Clone the AniDojo repository to your local machine:

git clone https://github.com/yourusername/anidojo.git
cd anidojo

Replace yourusername with the actual repository owner or organization name.

Install Dependencies

Install all required npm packages:

npm install

Key Dependencies Installed:

Package	Version	Purpose
next	^16.0.0	React framework with App Router
react	19.1.0	UI library with Server Components
@supabase/supabase-js	^2.78.0	Supabase client
@supabase/ssr	^0.7.0	Server-side rendering support
axios	^1.12.2	HTTP client for Jikan API
tailwindcss	^4	Utility-first CSS framework
typescript	^5	Type safety
lucide-react	^0.544.0	Icon library
zustand	^5.0.8	State management
react-hook-form	^7.63.0	Form handling
zod	^4.1.11	Schema validation
recharts	^3.2.1	Statistics charts

Installation may take 2-5 minutes depending on your internet connection and package manager.

Set Up Supabase Project

Create a Supabase Project

Go to supabase.com and sign in
Click “New Project”
Enter project details:
- Name: anidojo-dev
- Database Password: Generate a strong password (save it!)
- Region: Choose closest to you
Click “Create New Project”
Wait 2-3 minutes for project initialization

Get API Credentials

In your Supabase dashboard, go to Settings → API
Copy the following values:
- Project URL: https://[project-ref].supabase.co
- anon/public key: Long JWT token starting with eyJ...

Never commit the anon key to public repositories, even though it’s designed for client-side use. The service_role key should NEVER be used in client code.

Configure Environment Variables

Create a .env.local file in the project root:

touch .env.local

Environment Variable Reference:

Variable	Required	Description
`NEXT_PUBLIC_SUPABASE_URL`	Yes	Your Supabase project URL
`NEXT_PUBLIC_SUPABASE_ANON_KEY`	Yes	Supabase anonymous/public key

Variables prefixed with NEXT_PUBLIC_ are exposed to the browser. Never put secrets here!

You can verify your environment variables are loaded by checking process.env.NEXT_PUBLIC_SUPABASE_URL in any component.

Set Up Database Schema

AniDojo uses PostgreSQL through Supabase. You need to run the database migrations.

Option A: Using Supabase Dashboard (Recommended for Beginners)

Open your Supabase project dashboard
Navigate to SQL Editor (left sidebar)
Click “New Query”
Open the migration file: supabase/migrations/001_initial_schema.sql
Copy the entire SQL script
Paste into the SQL Editor
Click “Run” (or press Cmd/Ctrl + Enter)
Wait for success message
Verify tables in Table Editor

Tables Created:

profiles - User profiles
anime_entries - User anime lists
reviews - Anime reviews
review_votes - Helpful/unhelpful votes
comments - Review comments
comment_votes - Comment upvotes/downvotes
custom_lists - Custom anime lists
custom_list_entries - List entries

Option B: Using Supabase CLI (Recommended for Production)

npm install -g supabase

The migration includes database triggers for automatic profile creation and updated_at timestamps.

Set Up Storage Buckets

Create storage buckets for file uploads:

Create Buckets in Supabase Dashboard

Go to Storage in Supabase dashboard
Click “New Bucket”

Bucket 1: avatars

Name: avatars
Public: ✅ Yes
File size limit: 5 MB
Allowed MIME types: image/jpeg, image/png, image/webp, image/gif

Bucket 2: anime-images (Optional)

Name: anime-images
Public: ✅ Yes
File size limit: 10 MB
Allowed MIME types: image/jpeg, image/png, image/webp

Bucket 3: review-images (Optional)

Name: review-images
Public: ✅ Yes
File size limit: 10 MB
Allowed MIME types: image/jpeg, image/png, image/webp

Set Up Storage Policies

Run these SQL commands in the SQL Editor:

-- Allow public read access
CREATE POLICY "Avatar images are publicly accessible"
ON storage.objects FOR SELECT
USING (bucket_id = 'avatars');

-- Allow users to upload their own avatars
CREATE POLICY "Users can upload their own avatar"
ON storage.objects FOR INSERT
WITH CHECK (
  bucket_id = 'avatars' AND
  auth.uid()::text = (storage.foldername(name))[1]
);

-- Allow users to update their own avatars
CREATE POLICY "Users can update their own avatar"
ON storage.objects FOR UPDATE
USING (
  bucket_id = 'avatars' AND
  auth.uid()::text = (storage.foldername(name))[1]
);

Row Level Security ensures users can only manage their own avatar files.

Start Development Server

Run the development server with Turbopack:

npm run dev

The server will start on http://localhost:3000Expected Output:

▲ Next.js 16.0.0
- Local:        http://localhost:3000
- Turbopack:    enabled

✓ Ready in 2.3s

Turbopack provides faster hot module replacement (HMR) compared to Webpack.

Verify Installation

Test that everything is working:

Open Browser: Navigate to http://localhost:3000
Landing Page: You should see the auth landing page with anime data
Sign Up: Create a test account
- Email: [email protected]
- Password: testpassword123
Check Supabase:
- Go to Supabase dashboard → Authentication → Users
- Verify your test user appears
- Go to Table Editor → profiles
- Verify profile was auto-created
Test Features:
- Browse anime on the dashboard
- Add an anime to your list
- Write a review
- Check that data appears in Supabase tables

Use your browser’s DevTools (F12) to check for console errors or network issues.

Project Structure

Understand the codebase organization:

anidojo/
├── src/
│   ├── app/                    # Next.js App Router pages
│   │   ├── anime/[id]/        # Dynamic anime details
│   │   │   ├── page.tsx       # Anime info page
│   │   │   └── review/        # Write review page
│   │   ├── auth/              # Landing/auth page
│   │   ├── browse/            # Browse top anime
│   │   ├── dashboard/         # User dashboard
│   │   ├── discover/          # AI recommendations
│   │   ├── my-lists/          # User anime lists
│   │   ├── my-reviews/        # User reviews
│   │   ├── profile/           # User profile
│   │   ├── search/            # Search page
│   │   ├── settings/          # User settings
│   │   ├── signin/            # Sign in page
│   │   ├── signup/            # Sign up page
│   │   ├── upcoming/          # Upcoming anime
│   │   ├── layout.tsx         # Root layout
│   │   └── page.tsx           # Home (redirects to auth)
│   ├── components/            # React components
│   │   ├── AddAnimeModal.tsx  # Add anime to list modal
│   │   ├── AuthNavbar.tsx     # Auth page navbar
│   │   ├── GlobalSearch.tsx   # Search component
│   │   ├── Navbar.tsx         # Main navbar
│   │   └── Providers.tsx      # Context providers
│   ├── contexts/              # React contexts
│   │   └── AuthContext.tsx    # Authentication context
│   ├── hooks/                 # Custom React hooks
│   │   └── useAnime.ts        # Anime data hooks
│   ├── lib/                   # Utility libraries
│   │   ├── animeApi.ts        # Jikan API client
│   │   ├── mockData.ts        # Type definitions
│   │   ├── utils.ts           # Helper functions
│   │   └── supabase/          # Supabase utilities
│   │       ├── client.ts      # Browser client
│   │       ├── server.ts      # Server client
│   │       └── queries.ts     # Database queries
│   └── types/                 # TypeScript types
│       └── database.ts        # Database types
├── supabase/
│   └── migrations/
│       └── 001_initial_schema.sql  # Database schema
├── public/                    # Static assets
│   └── images/                # Images and icons
├── package.json               # Dependencies
├── tsconfig.json              # TypeScript config
├── tailwind.config.js         # Tailwind config
└── next.config.mjs            # Next.js config

Development Workflow

Running Build

npm run build

Environment-Specific Commands

Command	Description
`npm run dev`	Start dev server with Turbopack (hot reload)
`npm run build`	Build production bundle
`npm run start`	Start production server (run build first)
`npm run lint`	Run ESLint for code quality

Working with Supabase

supabase status

Common Development Tasks

Add a new database table

Create a new migration file: supabase/migrations/002_new_feature.sql
Write SQL for new table with RLS policies
Run migration: supabase db push
Generate new TypeScript types: supabase gen types typescript
Update queries in src/lib/supabase/queries.ts

Add a new page route

Create file in src/app/your-route/page.tsx
Export default component
Add to navigation in sidebar component
Update TypeScript types if needed

Test API rate limiting

The Jikan API has rate limits (3 requests/second). Test the rate limiter:

import { searchAnime, clearAPICache } from '@/lib/animeApi';

// Clear cache for testing
clearAPICache();

// Make multiple rapid requests
const results = await Promise.all([
  searchAnime('naruto'),
  searchAnime('bleach'),
  searchAnime('one piece')
]);

// Requests are automatically queued and rate-limited

Debug authentication issues

Check .env.local has correct Supabase credentials
Verify cookies are enabled in browser
Check Supabase dashboard → Authentication → Users
Check browser DevTools → Network tab for failed requests
Check RLS policies in Supabase SQL Editor:

SELECT * FROM profiles WHERE id = auth.uid();

Troubleshooting

Build Errors After Installing DependenciesTry:

rm -rf node_modules
rm package-lock.json
npm install

Supabase Connection Failed

Verify .env.local exists and has correct values
Restart dev server after changing env vars
Check Supabase project is active (not paused)
Verify project URL matches exactly (including https://)

Jikan API Errors (429 Rate Limited)

The API client includes automatic rate limiting
Wait 60 seconds and try again
Check network tab for failed requests
Consider implementing longer caching for development

TypeScript Errors

Run npm run build to see all errors
Check tsconfig.json is not modified
Regenerate database types: supabase gen types typescript
Clear Next.js cache: rm -rf .next

Testing

Manual Testing Checklist

Contributing

Want to contribute? Check the GitHub issues for open tasks or submit a pull request with new features!

Contribution Guidelines

Fork the repository
Create feature branch: git checkout -b feature/amazing-feature
Make changes with clear commit messages
Test thoroughly using the checklist above
Run linter: npm run lint
Submit pull request with description of changes

Code Style

Use TypeScript for type safety
Follow ESLint rules (npm run lint)
Use Tailwind CSS utility classes
Write clear component and function names
Add comments for complex logic
Keep components small and focused

Deployment

AniDojo can be deployed to various platforms:

Vercel

Recommended for Next.js apps

Connect GitHub repo
Add environment variables
Deploy automatically on push

Netlify

Alternative with similar featuresBuild command: npm run build Publish directory: .next

Docker

For self-hostingCreate Dockerfile with Node.js base image

Railway

Easy deployment with databaseConnects to GitHub and auto-deploys

Environment Variables for Production

Ensure these are set in your deployment platform:

NEXT_PUBLIC_SUPABASE_URL
NEXT_PUBLIC_SUPABASE_ANON_KEY

Never commit .env.local to version control! Use platform-specific environment variable settings.

Additional Resources

Need Help?

If you encounter issues during installation:

Check this documentation thoroughly
Search existing GitHub issues
Open a new GitHub issue with:
- Error message
- Steps to reproduce
- Your environment (OS, Node version, etc.)
- Screenshots if applicable

Get Started

Core Features

Setup Guides

User Guide

Developer Installation

Developer Installation Guide

Prerequisites

Node.js 18+

Package Manager

Git

Supabase Account

Installation Steps

Create a Supabase Project

Get API Credentials

Option A: Using Supabase Dashboard (Recommended for Beginners)

Option B: Using Supabase CLI (Recommended for Production)

Create Buckets in Supabase Dashboard

Set Up Storage Policies

Project Structure

Development Workflow

Running Build

Environment-Specific Commands

Working with Supabase

Common Development Tasks

Troubleshooting

Testing

Manual Testing Checklist

Contributing

Contribution Guidelines

Code Style

Deployment

Vercel

Netlify

Docker

Railway

Environment Variables for Production

Additional Resources

Need Help?

Build docs developers (and LLMs) love

Get Started

Core Features

Setup Guides

User Guide

​Developer Installation Guide

​Prerequisites

Node.js 18+

Package Manager

Git

Supabase Account

​Installation Steps

​Create a Supabase Project

​Get API Credentials

​Option A: Using Supabase Dashboard (Recommended for Beginners)

​Option B: Using Supabase CLI (Recommended for Production)

​Create Buckets in Supabase Dashboard

​Set Up Storage Policies

​Project Structure

​Development Workflow

​Running Build

​Environment-Specific Commands

​Working with Supabase

​Common Development Tasks

​Troubleshooting

​Testing

​Manual Testing Checklist

​Contributing

​Contribution Guidelines

​Code Style

​Deployment

Vercel

Netlify

Docker

Railway

​Environment Variables for Production

​Additional Resources

​Need Help?

Build docs developers (and LLMs) love

Developer Installation Guide

Prerequisites

Installation Steps

Create a Supabase Project

Get API Credentials

Option A: Using Supabase Dashboard (Recommended for Beginners)

Option B: Using Supabase CLI (Recommended for Production)

Create Buckets in Supabase Dashboard

Set Up Storage Policies

Project Structure

Development Workflow

Running Build

Environment-Specific Commands

Working with Supabase

Common Development Tasks

Troubleshooting

Testing

Manual Testing Checklist

Contributing

Contribution Guidelines

Code Style

Deployment

Environment Variables for Production

Additional Resources

Need Help?