Next.js

General Principles

Follow Airbnb JavaScript/React Style Guide for React and TypeScript.

Folder and File Structure

Follow Next JS Project Structure
And Community discussion

layout.tsx

page.tsx

global.css

layout.tsx

page.tsx

proxy.ts # 7. Gatekeeper Layer (Middleware)

.env

.env.example

components.json # Shadcn UI Configuration

next.config.ts # Next.js Configuration

package.json

tsconfig.json

eslint.config.mjs

prettier.config.ts

README.md

Naming Conventions

Use kebab-case for React component files, utility, hooks, or helper files.

What	How	Good	Bad
React component file	kebab-case	login-form.tsx	~~Login-Form.tsx~~
Custom Hooks	kebab-case, use first	use-config.ts	~~use-Config.tsx~~

Examples:

app/home/page.tsx
components/ui/button.tsx
components/login-form.tsx
hooks/use-fetch.ts
lib/format-date.ts

Imports

Organize imports from libraries to internal files:

// React or third-party libraries
import { useState } from 'react';
import { format } from 'date-fns';

// Internal components and helpers
import NavBar from '@/components/navbar';
import { formatDate } from '@/lib/format-date';

React Components

Use functional components
Use TypeScript for typing props and state.

Example:

interface LoginProps {
status?: string;
canResetPassword: boolean;

}

export default fanction LoginForm({status, canResetPassword}: LoginProps){

return (
  <div>LoginForm</div>

 )
}

TypeScript

Enable strict mode in tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2017",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "react-jsx",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": [
    "next-env.d.ts",
    "**/*.ts",
    "**/*.tsx",
    ".next/types/**/*.ts",
    ".next/dev/types/**/*.ts",
    "**/*.mts"
  ],
  "exclude": ["node_modules"]
}

Avoid using any. Always use specific types.

Example:

// Correct
const fetchUser = async (id: number): Promise<User> => {
  // ...
};

// Incorrect
const fetchUser = async (id: number): Promise<any> => {
  // ...
};

Styling

Use CSS Modules or Tailwind CSS for modular styling.

Example:

import styles from './NavBar.module.css';

const NavBar: React.FC = () => {
  return <nav className={styles.nav}>NavBar</nav>;
};

export default NavBar;

Global styles are stored in globals.css and imported in app/layout.tsx.

import './globals.css';

export const metadata = {
  title: 'Next.js App',
  description: 'Generated by Next.js',
};

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

Testing

see: https://nextjs.org/docs/app/guides/testing

Use Jest and React Testing Library for unit testing.

Example:

import { render, screen } from '@testing-library/react';
import Button from '@/components/Button';

test('renders Button with label', () => {
  render(<Button label="Click Me" onClick={() => {}} />);
  expect(screen.getByText(/Click Me/i)).toBeInTheDocument();
});

Use Playwright or Cypress for end-to-end testing.

Linting and Formatting

Use ESLint with the following configuration in eslint.config.mjs:

import { defineConfig, globalIgnores } from "eslint/config";
import nextVitals from "eslint-config-next/core-web-vitals";
import nextTs from "eslint-config-next/typescript";

const eslintConfig = defineConfig([
  ...nextVitals,
  ...nextTs,
  // Override default ignores of eslint-config-next.
  globalIgnores([
    // Default ignores of eslint-config-next:
    ".next/**",
    "out/**",
    "build/**",
    "next-env.d.ts",
  ]),
]);

export default eslintConfig;

Use Prettier with the following configuration in .prettierrc optional:

{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5",
  "printWidth": 80
}

Agent Skills

Terminal

  npx skills add https://github.com/ekovegeance/agent-skills --skill nextjs

Awesomecode theme and code editor setup for VS Code
Next.js MCP Server for coding agents
VSCode Extension: ESLint, Prettier, Tailwind CSS IntelliSense, Auto Rename Tag, Auto Close Tag, ES7+ React/Redux/React-Native snippets

On this page