Get Started: Developer Guide

Welcome to the comprehensive guide for the QUEORO Boilerplate. This document will walk you through setting up your project, adding new features, following best practices, and optimizing for maximum performance.

1. Setup & Initialization

How to Start a New Project

When you first clone this boilerplate, you need to customize it for your own application. Instead of doing this manually, use the built-in initialization script.

# 1. Install all dependencies
pnpm install

# 2. Run the interactive initialization script
pnpm run init-project

This script will ask for your app's name, description, and URL, and will automatically update package.json, src/lib/constants.ts, and the README.

Starting the Dev Server

# Copy environment variables
cp .env.example .env.local

# Start the development server on localhost:3000
pnpm dev

2. Building Features & Components

Automation & Generators (pnpm generate)

To ensure consistency and save time, we use Plop.js to scaffold new pages and components. Never manually create component or page files!

pnpm generate

1. Generating a Page

Select page from the menu. Enter your route path (e.g., contact or dashboard/settings).

You will then be asked: "Do you also want to generate a route layout (layout.tsx) for this page?" If you select y, it will automatically build both page.tsx and layout.tsx in the same folder!

The script will automatically scaffold src/app/[locale]/contact/page.tsx complete with the Next.js App Router boilerplate and internationalization hooks.

✨ Magic feature: The script will instantly open your messages/en.json and messages/si.json files and automatically inject the new translation namespace so your page never crashes!

💡 Pro Tip: Adding new keys later

If you add a new text key to the page later (e.g., t("submitBtn")), you can either manually add it to the JSON file inside your page's namespace, or simply run pnpm i18n:extract to have it automatically found and appended for you!

2. Generating a Route Layout (Standalone)

Select route-layout from the menu. This is used when you only need to create a wrapper for an existing folder of pages.

It generates a clean layout.tsx file where you can import your visual components (like Sidebars or Headers) to wrap around the {children}.

3. Generating a Component

Select component from the menu. Enter the component name (e.g., ContactForm).

Choose the directory:

ui: Generic, reusable bits (buttons, inputs).
features: Domain-specific chunks (forms, charts).
layout: Visual shell pieces (headers, sidebars, footers).

Choose whether it needs to be a Client Component ("use client"). The script will generate the file perfectly formatted.

3. Automated Scripts & Tooling

CLI Commands Reference

Beyond running the development server and scaffolding components, this boilerplate ships with several powerful scripts to automate testing, formatting, and performance tuning.

`pnpm run init-project`Project Initialization

An interactive wizard that renames the project, sets the URL, updates metadata, and configures monetization/ads automatically. Run this immediately after cloning the boilerplate.

`pnpm analyze`Bundle Analysis

Compiles a production build and opens an interactive visual map of your JavaScript bundle in your browser. This shows exactly which NPM packages are taking up the most space, helping you optimize load times by identifying heavy dependencies.

`pnpm test`and`pnpm test:coverage`

Runs the automated unit test suite using Vitest. The base test command watches your files for changes and re-runs tests instantly. The test:coverage command generates a detailed HTML report showing exactly which lines of code lack test coverage.

`pnpm i18n:extract`Translation Sync

Automatically scans all your React components for missing translation keys (like t("some.key")) and appends them to your messages/en.json and si.json files so you never forget to add them!

`pnpm ui:add`Add UI Components

Instead of going to the Shadcn UI documentation to find installation commands, run this command to open an interactive terminal checklist of all 40+ available UI components (like Dialogs, Dropdowns, DatePickers) and install them instantly.

`pnpm type-check`Fast TypeScript Check

A strict check of the entire codebase for TypeScript errors that finishes in a couple of seconds without actually doing a heavy Next.js build.

`pnpm clean`Nuke Cache

Sometimes Next.js or package managers get stuck caching old data. Run this to automatically delete .next, node_modules, clear the lockfile, and cleanly reinstall everything for a completely fresh start.

`pnpm format`and`pnpm lint`

Automates code styling. pnpm format runs Prettier across all files to instantly fix indentation, quotes, and spacing. pnpm lint runs ESLint and Next.js strict checks to catch unused variables, accessibility violations, or logic bugs.

`pnpm test`and`pnpm test:coverage`

Runs the Vitest testing suite. pnpm test starts "watch mode" to instantly re-run tests as you type code. pnpm test:coverage runs tests and generates an HTML report showing exactly which lines of code are missing tests.

Invisible Automation:Husky Pre-commit Hooks

You don't need to manually run the formatting scripts before saving your code to git! Every time you type git commit, a hidden script runs in the background. It automatically formats and lints the exact files you edited. If it catches a severe error, it blocks the commit, ensuring you never push broken code to your repository.

4. Customizing Theme (Colors & Fonts)

🎨 Changing Colors

This boilerplate uses Shadcn UI, which means all colors are controlled by CSS variables so they automatically switch between Light Mode and Dark Mode. There is no automated command for colors because design is highly custom.

To change your primary brand color, open src/styles/globals.css. At the top, you will see a :root block (for light mode) and a .dark block. Change the primary variable:

:root {
  /* Change this HSL value to your brand color */
  --primary: 221.2 83.2% 53.3%; /* This is blue */
}

Tip: If you don't know HSL colors, go to ui.shadcn.com/themes, pick a color you like, click "Copy Code", and paste it over your globals.css!

🔠 Changing Fonts

This project uses next/font/google, which means fonts are automatically downloaded at build time for maximum performance (no slow Google Fonts network requests).

To change your fonts:

Open src/app/layout.tsx.
At the top, change the imports to whatever you want (e.g., import { Roboto, Playfair_Display } from "next/font/google";).
Update the configuration variable inside the file:
const fontSans = Roboto({ subsets: ["latin"], variable: "--font-sans", });
Tailwind is already wired up to read these! Anywhere in your app, use font-sans (for body text) or font-heading (for titles) and it will instantly use your new fonts.

5. Best Practices

React Server Components (RSC) Default

Assume every component is a Server Component. Only add "use client"; to the top of a file if you absolutely need to use hooks (useState, useEffect), DOM event listeners (onClick), or browser-only APIs. This keeps the JavaScript payload minimal.

Styling & Tailwind Merge

When building a reusable UI primitive (like a Button), always accept a className prop and merge it using the cn() utility from src/lib/utils.ts. This prevents Tailwind class conflicts.

import { cn } from "@/lib/utils";

export function MyComponent({ className }) {
  return <div className={cn("base-styles bg-primary", className)} />;
}

CSS Variables Over Hex Colors

Do not use hardcoded hex colors like bg-[#123456]. Use the semantic CSS variables (e.g., bg-primary, text-muted-foreground) mapped in src/styles/globals.css. This ensures Dark Mode works perfectly without any extra effort.

6. Ultimate Performance Guide

This boilerplate is already heavily optimized (scoring 90+ on Lighthouse), but as you add features, follow these instructions to keep it blazing fast:

1. Image Optimization

Never use the native HTML <img> tag. Always use the Next.js <Image> component. For above-the-fold images (like the Hero image), always add the priority prop. Use quality={85} to dramatically reduce file size without visible degradation (this is configured in next.config.ts).

2. Analyze the Bundle

Periodically check if you are importing massive third-party libraries. Run the built-in analyzer command:

pnpm analyze

This will open a visual tree map of your JavaScript chunks in the browser. Look for giant red boxes and see if you can lazy-load them using next/dynamic.

3. Third-Party Scripts

If you add Google Analytics, Meta Pixel, or Intercom, do NOT put the raw script tag in your layout. Use the Next.js <Script> component with the correct strategy.

import Script from "next/script";

// Load analytics without blocking the main thread
<Script src="https://example.com/analytics.js" strategy="lazyOnload" />

7. The Golden Workflow

Follow this standard lifecycle every time you sit down to build a new feature or make changes in this boilerplate to ensure maximum productivity and safety:

🟢 Before & During Development

Start your engine: Run pnpm dev. Keep this running in your terminal the entire time you code for instant hot-reloading.
Scaffold new pieces: Need a new button? A new contact page? Don't create files manually! Open a second terminal window and run pnpm generate. It will instantly create the perfectly formatted files for you.

🟡 After You Finish Coding (Sanity Checks)

Once your feature works in the browser, run these commands to ensure it's truly production-ready before you save it to Git:

Make it pretty: Run pnpm format. This instantly fixes all your messy indentation, quotes, and spacing across the entire project.
Check for bugs: Run pnpm lint. This scans your code to make sure you didn't leave any unused variables, missing imports, or accessibility errors.
The Ultimate Test: Run pnpm build. This does a strict compile of your entire app. If it succeeds, it means you have zero TypeScript or routing errors, and your code is 100% safe to deploy!

🔴 Committing Your Code

Once everything is green:

Run git add . and git commit -m "added my new feature".
The Magic Safety Net: Thanks to the Husky pre-commit hooks built into this project, the terminal will briefly pause and automatically run the formatter and linter again on the files you just touched. If everything is good, the commit succeeds! If you broke something, it blocks the commit.

8. Automated Testing & CI/CD

🧪 Vitest & React Testing Library

When you use pnpm generate, a .test.tsx file is automatically created next to your component! This project uses extremely fast Vitest testing.

Watch Mode: Run pnpm test while you code. It instantly re-runs tests only for files you change.
Coverage Report: Run pnpm test:coverage to generate a beautiful HTML report showing exactly which lines of code need more tests.

🚀 GitHub Actions CI Pipeline

This boilerplate includes a pre-configured .github/workflows/ci.yml file. Every time you push code to GitHub or create a Pull Request, GitHub will automatically boot up a server and run:

Full environment setup and dependency caching
Code Formatting Check (Prettier)
Linting Check (ESLint)
TypeScript Type Checking
Vitest Test Suite
Next.js Production Build

If any of these steps fail, GitHub blocks the Pull Request from merging, ensuring your main branch is always 100% production-ready!

9. Monetization & Ads

This boilerplate includes a built-in, production-ready ad monetization layer supporting Google AdSense and Carbon Ads. By default, it is completely disabled, meaning there is zero performance or DOM cost.

🔌 Activating Ads

Ads are activated purely via environment variables. Add your publisher ID to .env.local:

NEXT_PUBLIC_ADSENSE_CLIENT_ID="ca-pub-XXXXXXXXXXXXXXXX"

Once set, the boilerplate automatically configures strict CSP headers, exposes a dynamic /ads.txt route for verification, and injects the necessary scripts.

🧩 Generating Ad Slots

Instead of copying and pasting ad scripts, you can instantly scaffold an ad unit component using Plop:

pnpm generate

Select ad-slot, choose your network (AdSense or Carbon), and it will generate a pre-configured, CLS-safe component in src/components/ads/slots/.

🇪🇺 GDPR & CCPA Ready

The useAdConsent() hook is deeply integrated. Ads will not render or inject tracking scripts until the user has given consent. In development mode (or if ads are disabled), placeholders will be shown to help you design your layouts perfectly.

1. Setup & Initialization

How to Start a New Project

When you first clone this boilerplate, you need to customize it for your own application. Instead of doing this manually, use the built-in initialization script.

# 1. Install all dependencies
pnpm install

# 2. Run the interactive initialization script
pnpm run init-project

This script will ask for your app's name, description, and URL, and will automatically update package.json, src/lib/constants.ts, and the README.

Starting the Dev Server

# Copy environment variables
cp .env.example .env.local

# Start the development server on localhost:3000
pnpm dev

2. Building Features & Components

Automation & Generators (pnpm generate)

To ensure consistency and save time, we use Plop.js to scaffold new pages and components. Never manually create component or page files!

pnpm generate

1. Generating a Page

Select page from the menu. Enter your route path (e.g., contact or dashboard/settings).

You will then be asked: "Do you also want to generate a route layout (layout.tsx) for this page?" If you select y, it will automatically build both page.tsx and layout.tsx in the same folder!

The script will automatically scaffold src/app/[locale]/contact/page.tsx complete with the Next.js App Router boilerplate and internationalization hooks.

✨ Magic feature: The script will instantly open your messages/en.json and messages/si.json files and automatically inject the new translation namespace so your page never crashes!

💡 Pro Tip: Adding new keys later

2. Generating a Route Layout (Standalone)

Select route-layout from the menu. This is used when you only need to create a wrapper for an existing folder of pages.

It generates a clean layout.tsx file where you can import your visual components (like Sidebars or Headers) to wrap around the {children}.

3. Generating a Component

Select component from the menu. Enter the component name (e.g., ContactForm).

Choose the directory:

ui: Generic, reusable bits (buttons, inputs).
features: Domain-specific chunks (forms, charts).
layout: Visual shell pieces (headers, sidebars, footers).

Choose whether it needs to be a Client Component ("use client"). The script will generate the file perfectly formatted.

3. Automated Scripts & Tooling

CLI Commands Reference

Beyond running the development server and scaffolding components, this boilerplate ships with several powerful scripts to automate testing, formatting, and performance tuning.

`pnpm run init-project`Project Initialization

An interactive wizard that renames the project, sets the URL, updates metadata, and configures monetization/ads automatically. Run this immediately after cloning the boilerplate.

`pnpm analyze`Bundle Analysis

`pnpm test`and`pnpm test:coverage`

`pnpm i18n:extract`Translation Sync

Automatically scans all your React components for missing translation keys (like t("some.key")) and appends them to your messages/en.json and si.json files so you never forget to add them!

`pnpm ui:add`Add UI Components

`pnpm type-check`Fast TypeScript Check

A strict check of the entire codebase for TypeScript errors that finishes in a couple of seconds without actually doing a heavy Next.js build.

`pnpm clean`Nuke Cache

`pnpm format`and`pnpm lint`

`pnpm test`and`pnpm test:coverage`

Invisible Automation:Husky Pre-commit Hooks

4. Customizing Theme (Colors & Fonts)

🎨 Changing Colors

To change your primary brand color, open src/styles/globals.css. At the top, you will see a :root block (for light mode) and a .dark block. Change the primary variable:

:root {
  /* Change this HSL value to your brand color */
  --primary: 221.2 83.2% 53.3%; /* This is blue */
}

Tip: If you don't know HSL colors, go to ui.shadcn.com/themes, pick a color you like, click "Copy Code", and paste it over your globals.css!

🔠 Changing Fonts

This project uses next/font/google, which means fonts are automatically downloaded at build time for maximum performance (no slow Google Fonts network requests).

To change your fonts:

Open src/app/layout.tsx.
At the top, change the imports to whatever you want (e.g., import { Roboto, Playfair_Display } from "next/font/google";).
Update the configuration variable inside the file:
const fontSans = Roboto({ subsets: ["latin"], variable: "--font-sans", });
Tailwind is already wired up to read these! Anywhere in your app, use font-sans (for body text) or font-heading (for titles) and it will instantly use your new fonts.

5. Best Practices

React Server Components (RSC) Default

Styling & Tailwind Merge

When building a reusable UI primitive (like a Button), always accept a className prop and merge it using the cn() utility from src/lib/utils.ts. This prevents Tailwind class conflicts.

import { cn } from "@/lib/utils";

export function MyComponent({ className }) {
  return <div className={cn("base-styles bg-primary", className)} />;
}

CSS Variables Over Hex Colors

6. Ultimate Performance Guide

This boilerplate is already heavily optimized (scoring 90+ on Lighthouse), but as you add features, follow these instructions to keep it blazing fast:

1. Image Optimization

2. Analyze the Bundle

Periodically check if you are importing massive third-party libraries. Run the built-in analyzer command:

pnpm analyze

This will open a visual tree map of your JavaScript chunks in the browser. Look for giant red boxes and see if you can lazy-load them using next/dynamic.

3. Third-Party Scripts

If you add Google Analytics, Meta Pixel, or Intercom, do NOT put the raw script tag in your layout. Use the Next.js <Script> component with the correct strategy.

import Script from "next/script";

// Load analytics without blocking the main thread
<Script src="https://example.com/analytics.js" strategy="lazyOnload" />

7. The Golden Workflow

Follow this standard lifecycle every time you sit down to build a new feature or make changes in this boilerplate to ensure maximum productivity and safety:

🟢 Before & During Development

Start your engine: Run pnpm dev. Keep this running in your terminal the entire time you code for instant hot-reloading.
Scaffold new pieces: Need a new button? A new contact page? Don't create files manually! Open a second terminal window and run pnpm generate. It will instantly create the perfectly formatted files for you.

🟡 After You Finish Coding (Sanity Checks)

Once your feature works in the browser, run these commands to ensure it's truly production-ready before you save it to Git:

Make it pretty: Run pnpm format. This instantly fixes all your messy indentation, quotes, and spacing across the entire project.
Check for bugs: Run pnpm lint. This scans your code to make sure you didn't leave any unused variables, missing imports, or accessibility errors.
The Ultimate Test: Run pnpm build. This does a strict compile of your entire app. If it succeeds, it means you have zero TypeScript or routing errors, and your code is 100% safe to deploy!

🔴 Committing Your Code

Once everything is green:

Run git add . and git commit -m "added my new feature".
The Magic Safety Net: Thanks to the Husky pre-commit hooks built into this project, the terminal will briefly pause and automatically run the formatter and linter again on the files you just touched. If everything is good, the commit succeeds! If you broke something, it blocks the commit.

8. Automated Testing & CI/CD

🧪 Vitest & React Testing Library

When you use pnpm generate, a .test.tsx file is automatically created next to your component! This project uses extremely fast Vitest testing.

Watch Mode: Run pnpm test while you code. It instantly re-runs tests only for files you change.
Coverage Report: Run pnpm test:coverage to generate a beautiful HTML report showing exactly which lines of code need more tests.

🚀 GitHub Actions CI Pipeline

This boilerplate includes a pre-configured .github/workflows/ci.yml file. Every time you push code to GitHub or create a Pull Request, GitHub will automatically boot up a server and run:

Full environment setup and dependency caching
Code Formatting Check (Prettier)
Linting Check (ESLint)
TypeScript Type Checking
Vitest Test Suite
Next.js Production Build

If any of these steps fail, GitHub blocks the Pull Request from merging, ensuring your main branch is always 100% production-ready!

9. Monetization & Ads

🔌 Activating Ads

Ads are activated purely via environment variables. Add your publisher ID to .env.local:

NEXT_PUBLIC_ADSENSE_CLIENT_ID="ca-pub-XXXXXXXXXXXXXXXX"

Once set, the boilerplate automatically configures strict CSP headers, exposes a dynamic /ads.txt route for verification, and injects the necessary scripts.

🧩 Generating Ad Slots

Instead of copying and pasting ad scripts, you can instantly scaffold an ad unit component using Plop:

pnpm generate

Select ad-slot, choose your network (AdSense or Carbon), and it will generate a pre-configured, CLS-safe component in src/components/ads/slots/.

1. Setup & Initialization

How to Start a New Project

Starting the Dev Server

2. Building Features & Components

Automation & Generators (pnpm generate)

1. Generating a Page

2. Generating a Route Layout (Standalone)

3. Generating a Component

3. Automated Scripts & Tooling

CLI Commands Reference

pnpm run init-projectProject Initialization

pnpm analyzeBundle Analysis

pnpm testandpnpm test:coverage

pnpm i18n:extractTranslation Sync

pnpm ui:addAdd UI Components

pnpm type-checkFast TypeScript Check

pnpm cleanNuke Cache

pnpm formatandpnpm lint

pnpm testandpnpm test:coverage

Invisible Automation:Husky Pre-commit Hooks

4. Customizing Theme (Colors & Fonts)

🎨 Changing Colors

🔠 Changing Fonts

5. Best Practices

React Server Components (RSC) Default

Styling & Tailwind Merge

CSS Variables Over Hex Colors

6. Ultimate Performance Guide

1. Image Optimization

2. Analyze the Bundle

3. Third-Party Scripts

7. The Golden Workflow

🟢 Before & During Development

🟡 After You Finish Coding (Sanity Checks)

🔴 Committing Your Code

8. Automated Testing & CI/CD

🧪 Vitest & React Testing Library

🚀 GitHub Actions CI Pipeline

9. Monetization & Ads

🔌 Activating Ads

🧩 Generating Ad Slots

🇪🇺 GDPR & CCPA Ready

1. Setup & Initialization

How to Start a New Project

Starting the Dev Server

2. Building Features & Components

Automation & Generators (pnpm generate)

1. Generating a Page

2. Generating a Route Layout (Standalone)

3. Generating a Component

3. Automated Scripts & Tooling

CLI Commands Reference

pnpm run init-projectProject Initialization

pnpm analyzeBundle Analysis

pnpm testandpnpm test:coverage

pnpm i18n:extractTranslation Sync

pnpm ui:addAdd UI Components

pnpm type-checkFast TypeScript Check

pnpm cleanNuke Cache

pnpm formatandpnpm lint

pnpm testandpnpm test:coverage

Invisible Automation:Husky Pre-commit Hooks

4. Customizing Theme (Colors & Fonts)

🎨 Changing Colors

🔠 Changing Fonts

5. Best Practices

React Server Components (RSC) Default

Styling & Tailwind Merge

CSS Variables Over Hex Colors

6. Ultimate Performance Guide

1. Image Optimization

2. Analyze the Bundle

3. Third-Party Scripts

7. The Golden Workflow

🟢 Before & During Development

🟡 After You Finish Coding (Sanity Checks)

🔴 Committing Your Code

8. Automated Testing & CI/CD

🧪 Vitest & React Testing Library

🚀 GitHub Actions CI Pipeline

`pnpm run init-project`Project Initialization

`pnpm analyze`Bundle Analysis

`pnpm test`and`pnpm test:coverage`

`pnpm i18n:extract`Translation Sync

`pnpm ui:add`Add UI Components

`pnpm type-check`Fast TypeScript Check

`pnpm clean`Nuke Cache

`pnpm format`and`pnpm lint`

`pnpm test`and`pnpm test:coverage`

`pnpm run init-project`Project Initialization

`pnpm analyze`Bundle Analysis

`pnpm test`and`pnpm test:coverage`

`pnpm i18n:extract`Translation Sync

`pnpm ui:add`Add UI Components

`pnpm type-check`Fast TypeScript Check

`pnpm clean`Nuke Cache

`pnpm format`and`pnpm lint`

`pnpm test`and`pnpm test:coverage`