Project Initialization

When purchasing the template, you'll be asked to provide your GitHub username. After successful purchase, repository access permissions will be automatically sent to the user.

You can accept the NextDevKit repository invitation in your GitHub account's associated email or at GitHub Notifications.

Once you can open the corresponding NextDevKit code repository webpage, you've accepted the invitation and have permission to clone and read the code.

GITHUB Template Links:

• Next.js Starter Kit: https://github.com/nextdevkit/nextdevkit-template
• Cloudflare Workers Template Link: https://github.com/nextdevkit/nextdevkit-cloudflare-template
• SST AWS Template Link: https://github.com/nextdevkit/nextdevkit-aws-template

Managing Code Repository

After getting access, you need to copy the code to your private repository for development. Depending on your use case, you have the following options:

Method 1: Fork Repository (Single Project Only)

⚠️ Important Limitation: GitHub only allows you to fork a repository once. If you need to create multiple projects, use Method 2 or Method 3.

Use Cases:

• You only need to create one project based on NextDevKit
• You want to sync updates from the upstream repository
• You want to submit PRs to the original repository (if needed)

Steps:

1. Click the "Fork" button in the upper right corner of the NextDevKit template repository page
2. Select your GitHub account or organization
3. Make sure to check "Copy the main branch only"
4. Clone the forked repository to your local machine for development

Pros:

• Can sync upstream updates using GitHub's "Sync fork" feature
• Preserves complete Git history
• Can submit PRs to the original repository

Cons:

• Each GitHub account can only fork once, not suitable for multiple projects

Method 2: Clone + Manual Repository Creation (Recommended for Multiple Projects)

Use Cases:

• You need to create multiple projects based on NextDevKit
• You want each project to have its own independent Git repository
• You don't need to sync upstream updates, or prefer manual merging

Steps:

1. Clone the source repository locally:

git clone https://github.com/nextdevkit/nextdevkit-template.git my-project-name
cd my-project-name

2. Create a new private repository on GitHub, then connect:

git remote add origin https://github.com/your-username/your-new-repo.git
git branch -M main
git push -u origin main

Pros:

• Can create unlimited projects
• Each project is managed independently

Method 3: Using GitHub CLI (Most Convenient, Recommended)

Use Cases:

• You need to quickly create multiple projects
• You want to automate the repository creation process
• You already have GitHub CLI installed

Steps:

1. Ensure GitHub CLI is installed and logged in:

gh auth login

2. Clone and create new repository (one command):

# Download template code
git clone https://github.com/nextdevkit/nextdevkit-template.git my-project-name
cd my-project-name

# Remove original git history
rm -rf .git
git init

# Use gh to create new repository and push
gh repo create my-project-name --private --source=. --push

Pros:

• Fastest and most convenient method
• One command automatically creates remote repository and pushes
• Ideal for frequent project creation

Important Reminders

Regardless of which method you use, you must ensure:

1. ✅ Use a Private Repository
2. ❌ Do not commit code to public repositories
3. ⚠️ If collaborating, only invite authorized team members

Thank you for your understanding and cooperation!

Clone Code (For Methods 1 & 2)

When cloning code, there are two common methods: HTTPS and SSH.

HTTPS Method

For HTTPS cloning, we recommend using GitHub's official CLI tool gh. Refer to the gh official installation docs for installation.

If you're using gh tool for the first time, you need to login first.

gh auth login

If you've used gh tool before and are already logged in but still can't clone the code, check if your gh login account is correct.

gh auth status

If the login account is incorrect, you need to login again.

Then you can use the traditional git clone command. Remember to replace the repository URL you need to clone.

git clone https://github.com/nextdevkit/nextdevkit-template.git

SSH Method

The second method is to use SSH to clone code. First, you need to generate SSH keys. You can change ed25519 to another name.

ssh-keygen -t ed25519 -C "your_email@example.com"

Then add the generated public key to GitHub.

cat ~/.ssh/id_ed25519.pub

In the upper right corner of GitHub, click your avatar, then click Settings. In the "Access" section of the sidebar, click SSH and GPG keys. Click New SSH key or Add SSH key. Paste the generated public key into the Key text box. Click the Add SSH key button.

For more details, refer to the GitHub official documentation.

Then you can use SSH to clone the code.

git clone git@github.com:nextdevkit/nextdevkit-template.git

Both methods are commonly used for cloning private repositories. Choose based on your preference.

Installing IDE Plugins

IDE Selection

When choosing an IDE, you can follow your habits. Since the author mainly uses Cursor for development, this tutorial recommends VSCode and its derivatives like Cursor as the IDE.

The following recommended IDE plugins are based on VSCode. If you use IDEA or WebStorm, please adjust accordingly.

After cloning the code, you need to install some IDE plugins to help with development and linting.

"Must-have" doesn't mean you can't develop without these plugins, but having them greatly improves development efficiency.

Must-have Plugins

• Biome(biomejs.biome): A modern JavaScript and TypeScript linter.
• i18n-ally(Lokalise.i18n-ally): An i18n helper tool.

Both plugins are configured by default in the .vscode directory's extensions.json file in the code, so VSCode will automatically prompt you to install these two plugins when you open the code. You just need to click install. If it doesn't prompt or you don't see it, just manually search for the plugin names and click install.

Recommended Plugins

• Git Graph(mhutchie.git-graph): A Git helper tool that makes it easier to view Git commit history and branches.
• MDX(unifiedjs.vscode-mdx): MDX helper tool for easier MDX file writing.
• Tailwind CSS IntelliSense(bradlc.vscode-tailwindcss): Tailwind CSS helper tool for easier Tailwind CSS file writing.
• Git History(donjayamanne.githistory): A Git helper tool for easier viewing of Git commit history and branches.

Configure Format on Save

To improve development efficiency, we strongly recommend configuring your IDE to automatically format code when saving files.

VSCode / Cursor Configuration

Good News: No manual configuration needed for VSCode and Cursor users!

NextDevKit project comes pre-configured with auto-formatting in the .vscode/settings.json file. These settings automatically take effect when you open the project with VSCode or Cursor.

The default configuration in the project:

{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "editor.formatOnPaste": true,
  "[javascript]": {
    "editor.defaultFormatter": "biomejs.biome",
    "javascript.preferences.importModuleSpecifier": "non-relative"
  },
  "[typescript]": {
    "editor.defaultFormatter": "biomejs.biome",
    "typescript.preferences.importModuleSpecifier": "non-relative"
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "biomejs.biome",
    "typescript.preferences.importModuleSpecifier": "non-relative"
  },
  "editor.codeActionsOnSave": {
    "quickfix.biome": "explicit",
    "source.organizeImports.biome": "explicit"
  }
}

Configuration explanation:

• editor.formatOnSave: true: Automatically format code when saving files
• editor.formatOnPaste: true: Automatically format code when pasting
• editor.defaultFormatter: "biomejs.biome": Use Biome as the default formatter
• editor.codeActionsOnSave: Automatically perform quick fixes and organize imports on save
• importModuleSpecifier: "non-relative": Use non-relative import paths (e.g., @/components instead of ../../components)

Just make sure you have the Biome plugin (biomejs.biome) installed, and your code will be automatically formatted when you save files.

Node.js and pnpm

In NextDevKit, we use Node.js v20+ as the development environment by default. You can also install the latest stable version of Node.js.

You can also use nvm or other version management tools to manage Node.js versions. Refer to the nvm official installation docs for installation.

brew install nvm

nvm install --lts
nvm use --lts

Use pnpm as the package manager. You can install pnpm with the following command.

npm install -g pnpm@10.10.0

Then install all dependencies.

pnpm install

If pnpm install fails, please check your network or OS version compatibility. Currently, only one user using an old macOS version encountered pnpm install failure with the error message e_modules/@cloudflare/workerd-darwin-64/bin/workerd'Expected in: '/usr/lib/libc++.1.dylib'. Upgrading the system solved the problem. If you have other issues, please get help in the discord community.

Lint and Format

After installing dependencies, it's time to prepare the local development environment. Linting and formatting are two very important steps in code development.

You can follow NextDevKit's default configuration or configure according to your own needs.

• Linting:

Analyzes potential errors, bugs, and code quality issues in code. Checks code style consistency and best practices. For example: unused variables, missing semicolons, using == instead of ===.

• Formatting:

Unifies code appearance and layout, handling indentation, line breaks, spaces, quotes, etc. Doesn't change code logic, only changes display format.

Common lint and format tools include Biome, ESLint, Prettier, etc. NextDevKit integrates Biome by default with configured lint and format rules.

For modern Next.js projects, I recommend using Biome because:

1. Simple configuration, low maintenance cost.
2. Better performance.
3. One tool solves two problems.
4. Good integration with modern development workflows.

For existing projects, if migration costs aren't high, I also recommend gradually migrating to Biome.

Here are their differences for reference. If you're not familiar, you can skip to the usage section and use the template's default configuration:

Biome vs ESLint + Prettier

ESLint + Prettier (Traditional Solution)

// .eslintrc.json
{
  "extends": ["eslint:recommended"],
  "rules": {
    "no-unused-vars": "error",
    "prefer-const": "warn"
  }
}

// .prettierrc
{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2
}

Pros:

• Mature ecosystem, rich plugins
• Good community support, complete documentation
• Highly customizable

Cons:

• Need to configure two tools
• Possible rule conflicts
• Relatively slower performance

Biome (Modern All-in-One Solution)

{
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "suspicious": {
        "noDebugger": "error"
      }
    }
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2
  }
}

Pros:

• One tool handles both linting and formatting
• Better performance (written in Rust)
• Simple configuration, works out of the box
• No conflicts between tools

Cons:

• Relatively new, ecosystem still developing
• Fewer custom rules
• May not support some special requirements

Common Biome Configuration and Usage

In package.json, use the default script commands to perform linting and formatting.

{
  "scripts": {
    "lint": "biome check --write .",
    "lint:fix": "biome check --fix --unsafe .",
    "format": "biome format --write .",
  }
}

Use the following commands for linting and formatting.

pnpm lint
pnpm lint:fix
pnpm format

Command Comparison Summary

Git hooks

The above lint and format commands need to be run manually. If you need them to run automatically before commit or push, you can use the following git hooks.

Since some developers don't like adding hooks functionality, NextDevKit doesn't include hooks by default.

If you're doing team development or need to add hooks functionality, consider these tools:

1. Husky
2. lefthook

Configuration Files

After setting up your development environment, it's important to understand the core configuration files that control your Next.js application.

package.json

package.json is the core configuration file for any Next.js project, defining project metadata, dependencies, and executable scripts.

You can modify the project name and description:

{
  "name": "nextdevkit",
  "version": "1.0.0",
  "description": "next.js template with authentication, payment, and more",
  "packageManager": "pnpm@10.10.0"
}

NextDevKit provides a complete set of development and build scripts:

{
  "scripts": {
    // Development related
    "dev": "next dev --turbopack",
    "build": "next build",
    "start": "next start",
    
    // Code quality
    "lint": "biome check --write .",
    "lint:fix": "biome check --fix --unsafe .",
    "format": "biome format --write .",
    
    // Database operations
    "db:generate": "drizzle-kit generate",
    "db:migrate": "drizzle-kit migrate",
    "db:studio": "drizzle-kit studio"
  }
}

next.config.ts

The next.config.ts file configures Next.js build and runtime behavior. NextDevKit includes optimized settings for modern web applications by default.

Current NextDevKit Configuration:

import { createMDX } from "fumadocs-mdx/next";
import type { NextConfig } from "next";
import createNextIntlPlugin from "next-intl/plugin";

const withMDX = createMDX();

const nextConfig: NextConfig = {
	// output: "standalone",
	images: {
		remotePatterns: [
			{
				hostname: "**",
			},
		],
	},
};

const withNextIntl = createNextIntlPlugin();

export default withMDX(withNextIntl(nextConfig));

Important Configuration Notes:

• Containerization: If deploying to containerized environments (AWS ECS, Railway, Fly.io), use output: "standalone"
• Image Domains: The current template uses ** for all domains (for convenience). For security, modify to specific domains
• Image Optimization: Vercel's image optimization may cause high costs. Disable with images: { unoptimized: true } if needed

For more details, visit Next.js Image Configuration Documentation.

TypeScript Configuration

NextDevKit's TypeScript configuration ensures type safety and optimal development experience.

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

In most cases, you only need to change the paths configuration to customize your project path mapping.

Path Mapping Benefits:

// Before (relative imports)
import Button from '../../../components/ui/button';

// After (absolute imports with path mapping)
import Button from '@/components/ui/button';