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 have two ways to clone the code to your private repository.

The first way is to fork the code repository to your GitHub account. After clicking fork, you can see a forked private repository under your GitHub account.

You can clone this private repository to your local machine, then use git commit and git push. The advantage of this method is that you can sync code from the source repository on GitHub and view code change history, and create PRs.

The second way is to directly clone the code repository to your local machine. Then create a new private repository in your organization or personal account, and push the cloned code to your private repository.

Both methods require you to use a private repository. Please do not commit code to public repositories. Thank you!

Clone Code

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.

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

Summary

Great! Now your local development environment is ready. Next, you can start local development.