Skip to main content
Set up your development environment and learn the workflow for contributing to AnimeThemes Web.

​
Prerequisites

Before you begin development, ensure you have:
  • Node.js v18 or higher (v24 recommended)
  • npm, yarn, or pnpm package manager
  • Git for version control
  • A local instance of the AnimeThemes API (recommended) or access to the production API

​
Development Server

​
Starting the Dev Server

Run the development server with hot reload: 
npm run dev
The application will be available at http://localhost:3000.

​
Turbopack

The development server uses Turbopack, Next.js’s next-generation bundler:
  • ⚡ Faster startup - Significantly faster than Webpack
  • 🔄 Instant HMR - Hot module replacement happens almost instantly
  • 🎯 Optimized builds - Efficient bundling and tree-shaking
Turbopack is enabled by default via the --turbopack flag in the dev script. It provides a much faster development experience than the traditional Webpack bundler.

​
Available Scripts

​
dev
string
Starts the Next.js development server with Turbopack and hot reload on port 3000.
npm run dev
​
build
string
Builds the application for production, generating static pages and optimized bundles.
npm run build
​
start
string
Starts the production server. Requires running npm run build first.
npm run start
​
lint
string
Runs ESLint to check for code quality issues.
npm run lint
​
type-check
string
Runs TypeScript compiler in check mode to verify types without emitting files.
npm run type-check
​
graphql-codegen
string
Generates TypeScript types from GraphQL schema and queries.
npm run graphql-codegen
​
compile-config
string
Compiles the TypeScript Next.js config to JavaScript. Runs automatically before dev/build/start.
npm run compile-config

​
Project Structure

animethemes-web/
├── public/              # Static assets (images, icons, etc.)
├── src/
│   ├── components/      # React components
│   ├── context/         # React context providers
│   ├── generated/       # Generated GraphQL types
│   ├── hooks/           # Custom React hooks
│   ├── lib/             # Library code and utilities
│   │   ├── client/      # Client-side utilities
│   │   ├── common/      # Shared utilities
│   │   └── server/      # Server-side utilities
│   ├── pages/           # Next.js pages (routing)
│   ├── styles/          # Global styles
│   ├── theme/           # Theme configuration
│   └── utils/           # Utility functions
├── next.config.ts       # Next.js configuration
├── tsconfig.json        # TypeScript configuration
└── package.json         # Dependencies and scripts

​
Path Aliases

TypeScript path aliases are configured for cleaner imports: 
import { Button } from "@/components/button/Button";
import { fetchData } from "@/lib/server";
import theme from "@/theme";
import { API_URL } from "@/utils/config";
The @/ alias maps to the src/ directory.

​
Styling with styled-components

Components use styled-components for CSS-in-JS: 
import styled from "styled-components";

const Button = styled.button`
  padding: 8px 16px;
  background: ${(props) => props.theme.colors["solid-primary"]};
  color: ${(props) => props.theme.colors["text-on-primary"]};
  border-radius: 4px;

  &:hover {
    opacity: 0.9;
  }
`;
See the Styling documentation for more details.

​
GraphQL Development

​
Generating Types

After modifying GraphQL queries or schemas, regenerate TypeScript types: 
npm run graphql-codegen
This reads:
  • src/lib/common/animethemes/type-defs.ts - AnimeThemes API schema
  • src/lib/server/animebracket/type-defs.ts - AnimeBracket schema
  • All .ts and .tsx files with GraphQL queries
And generates:
  • src/generated/graphql.ts - TypeScript types for queries
  • src/generated/graphql-resolvers.ts - TypeScript types for resolvers

​
Writing Queries

Use the gql template tag for type-safe queries: 
import gql from "graphql-tag";

const ANIME_QUERY = gql`
  query AnimeDetail($slug: String!) {
    anime(slug: $slug) {
      name
      year
      season
      themes {
        slug
        type
      }
    }
  }
`;

​
Git Workflow

​
Branch Naming

Use descriptive branch names:
  • feature/add-playlist-export
  • fix/video-player-controls
  • refactor/theme-context

​
Commit Messages

Follow conventional commit format: 
git commit -m "feat: add playlist export functionality"
git commit -m "fix: resolve video player control z-index issue"
git commit -m "refactor: extract theme logic to custom hook"

​
Pre-commit Hooks

Husky runs checks before each commit:
  • Linting via ESLint
  • Type checking via TypeScript
  • Code formatting via Prettier

​
Debugging

​
Browser DevTools

Use React DevTools for component inspection and the browser console for debugging.

​
VS Code Debugging

Create .vscode/launch.json: 
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Next.js: debug server-side",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "port": 9229,
      "console": "integratedTerminal"
    }
  ]
}

​
Verbose Logging

Enable verbose logs via environment variable: 
NEXT_PUBLIC_VERBOSE_LOGS=true npm run dev

​
Performance Optimization

​
Build Time Caching

The project uses build-time caching to speed up static generation:
next.config.ts
experimental: {
  // Single-threaded builds enable caching between pages
  workerThreads: false,
  cpus: 1,
}

​
Bundle Analysis

Analyze the bundle size: 
ANALYZE=true npm run build
This opens an interactive treemap showing bundle composition.

​
Common Development Tasks

  1. Create a file in src/pages/ (e.g., src/pages/about.tsx)
  2. Implement getStaticProps for data fetching
  3. Add the page to navigation if needed
See Adding Pages for details.
  1. Create a directory in src/components/ (e.g., src/components/my-component/)
  2. Add component file and styled components
  3. Export from the component directory
See Creating Components for details.
  1. Define the query with gql tag
  2. Use fetchData in getStaticProps
  3. Run npm run graphql-codegen to generate types
See Working with API for details.
  1. Update src/theme/colors/index.ts
  2. Restart the dev server
  3. Test both light and dark modes
See Theming for details.

​
Testing

Run type checking to catch TypeScript errors: 
npm run type-check
Run linting to check code quality: 
npm run lint
Set up your IDE to run ESLint and TypeScript checking automatically for immediate feedback while coding.

​
Next Steps

Add a Page

Learn how to create new pages

Create Components

Build reusable React components

Work with API

Fetch data from the AnimeThemes API

Deploy

Deploy your changes to production

Build docs developers (and LLMs) love

Get started for freeTalk to us