### Start Development Server

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/en/background-jobs.mdx

Run the local development server to start your application.

```bash
pnpm dev
```

--------------------------------

### Create Local Environment File

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/en/quick-start.mdx

Copy the example environment file to create a local configuration. This is essential for setting up local variables.

```bash
cp .env.example .env.local
```

```powershell
Copy-Item .env.example .env.local
```

--------------------------------

### Example Feature Module Structure

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/en/customization.mdx

Recommended file and directory structure for a new feature module.

```txt
src/features/example/
├── actions.ts
├── components/
├── schemas/
├── types.ts
└── index.ts
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/en/quick-start.mdx

Clone the NextDevTpl repository and install project dependencies using pnpm.

```bash
git clone git@github.com:evepupil/NextDevTpl.git
cd NextDevTpl
pnpm install
```

--------------------------------

### Launch Drizzle Studio

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/en/database.mdx

Start Drizzle Studio to visually inspect and interact with your local database. This is useful for debugging and understanding data structure.

```bash
pnpm db:studio
```

--------------------------------

### Run Self-Hosted Build and Deploy Script

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/en/deployment.mdx

Execute the local script to build, package, upload artifacts, and start the application on the server. Ensure SSH host, deploy path, and key path are configured in the script.

```bat
deploy-build.bat
```

--------------------------------

### Linux Production Start Script

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/en/project-structure.mdx

A shell script for Linux to start the production application. This script is intended for deployment on Linux environments.

```sh
start-prod.sh
```

--------------------------------

### Server Action Tiers Example

Source: https://github.com/evepupil/nextdevtpl/blob/master/CLAUDE.md

Defines custom server actions with different middleware for logging, authentication, and authorization using next-safe-action.

```typescript
const withFeatureAction = (name: string) =>
  protectedAction.metadata({ action: `feature.${name}` });

export const myAction = withFeatureAction("myAction")
  .schema(zodSchema)
  .action(async ({ parsedInput, ctx }) => { /* ... */ });
```

--------------------------------

### Docker Base Image Configuration

Source: https://github.com/evepupil/nextdevtpl/blob/master/README.md

A basic Dockerfile structure for building the Next.js application. It specifies the Node.js version and serves as a starting point for a production Docker image.

```dockerfile
FROM node:20-alpine AS base
# ... pnpm install, build, start
```

--------------------------------

### Push Local Database Schema

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/en/database.mdx

Use this command to apply schema changes directly to your local development database. It's suitable for initial setup or rapid iteration.

```bash
pnpm db:push
```

--------------------------------

### 常用命令

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/zh/quick-start.mdx

列出了 NextDevTpl 项目中常用的 pnpm 命令，包括开发、构建、数据库操作和测试。

```bash
pnpm dev            # 启动 Next.js 开发服务
pnpm build          # 生产构建
pnpm start          # 启动生产服务
pnpm typecheck      # TypeScript 类型检查
pnpm lint           # Biome lint
pnpm check          # Biome check 并自动修复
pnpm db:push        # 开发环境推送 Drizzle schema
pnpm db:generate    # 生成迁移文件
pnpm db:migrate     # 执行迁移
pnpm db:studio      # 打开 Drizzle Studio
pnpm test:run       # 单次运行测试
```

--------------------------------

### New Product Feature Directory

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/en/customization.mdx

Add new product-specific code and components under this directory structure.

```txt
src/features/<your-feature>
```

--------------------------------

### Sentry Environment Variables

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/en/observability.mdx

Configure these environment variables for Sentry error monitoring. NEXT_PUBLIC_SENTRY_DSN is for client-side setup, and SENTRY_AUTH_TOKEN is for server-side authentication.

```bash
NEXT_PUBLIC_SENTRY_DSN="https://..."
SENTRY_AUTH_TOKEN="sntrys_..."
```

--------------------------------

### Development and Build Commands

Source: https://github.com/evepupil/nextdevtpl/blob/master/CLAUDE.md

Common commands for running the development server, building for production, linting, formatting, type checking, and database operations.

```bash
pnpm dev              # Dev server (Turbopack)
pnpm build            # Production build
pnpm lint             # Biome lint
pnpm format           # Biome format
pnpm check            # Biome check + autofix
pnpm typecheck        # tsc --noEmit
pnpm db:push          # Push Drizzle schema to database
pnpm db:generate      # Generate Drizzle migrations
pnpm db:studio        # Open Drizzle Studio GUI
pnpm test             # Vitest (watch mode)
pnpm test:run         # Vitest (single run)
pnpm test:run -- src/test/path/to/file.test.ts  # Run single test file
```

--------------------------------

### 快速启动 NextDevTpl 项目

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/blog/zh/nextdevtpl-linuxdo-intro.mdx

克隆仓库、安装依赖、配置环境变量、推送数据库并启动开发服务器。

```bash
git clone git@github.com:evepupil/NextDevTpl.git
cd NextDevTpl
pnpm install
cp .env.example .env.local
pnpm db:push
pnpm dev
```

--------------------------------

### Run Payment Tests

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/en/payments.mdx

Execute payment and subscription tests using the provided command. Ensure you have the correct test suite path.

```bash
pnpm test:run src/test/payment
```

--------------------------------

### 新增语言步骤

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/zh/internationalization.mdx

添加新语言到项目中的步骤，包括配置、消息文件、文档和导航更新。

```markdown
1. 在 `src/i18n/routing.ts` 添加 locale。
2. 新增 `messages/<locale>.json`。
3. 新增 `src/content/docs/<locale>`。
4. 如果博客和法律页面也支持该语言，也要补对应内容。
5. 必要时更新 sitemap metadata。
6. 测试导航和语言切换。
```

--------------------------------

### 克隆并运行 NextDevTpl

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/blog/zh/hello-world.mdx

克隆 NextDevTpl 仓库，安装依赖并启动开发服务器以开始使用。

```bash
git clone https://github.com/nextdevtpl/nextdevtpl.git
cd nextdevtpl
pnpm install
pnpm dev
```

--------------------------------

### Common Development Commands

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/en/quick-start.mdx

A list of frequently used commands for managing the Next.js development server, build process, database operations, and linting.

```bash
pnpm dev            # Start Next.js dev server
pnpm build          # Create a production build
pnpm start          # Start production server
pnpm typecheck      # Run TypeScript type checking
pnpm lint           # Run Biome lint
pnpm check          # Run Biome check with fixes
pnpm db:push        # Push Drizzle schema in development
pnpm db:generate    # Generate migration files
pnpm db:migrate     # Run migrations
pnpm db:studio      # Open Drizzle Studio
pnpm test:run       # Run tests once
```

--------------------------------

### Self-hosted Deployment Script (Windows)

Source: https://github.com/evepupil/nextdevtpl/blob/master/README.md

This batch script automates the build, packaging, transfer, and restart process for self-hosting the application on a remote server. Ensure SSH host and key paths are configured at the top of the script.

```bat
:: Windows local machine
deploy-build.bat
```

--------------------------------

### Development and Build Scripts

Source: https://github.com/evepupil/nextdevtpl/blob/master/README.md

A collection of pnpm scripts for common development tasks, including running the development server, building for production, linting, formatting, type checking, database operations, and running tests.

```bash
pnpm dev            # Next.js dev (Turbopack)
pnpm build          # Production build
pnpm start          # Production server
pnpm lint           # Biome lint
pnpm format         # Biome format
pnpm check          # lint + format in fix mode
pnpm typecheck      # tsc --noEmit
pnpm db:generate    # Drizzle kit generate
pnpm db:push        # Drizzle kit push (dev)
pnpm db:studio      # Drizzle Studio UI
pnpm test           # Run integration tests
```

--------------------------------

### Run Support Tests

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/en/admin-and-support.mdx

Execute the support-related tests using the pnpm test:run command.

```bash
pnpm test:run src/test/support
```

--------------------------------

### Run Typechecking and Linting

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/en/customization.mdx

Execute these commands before committing to ensure code quality and type safety.

```bash
pnpm typecheck
pnpm lint
```

--------------------------------

### Axiom Logging Environment Variables

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/en/observability.mdx

Set these environment variables to enable shipping logs to Axiom. Ensure AXIOM_TOKEN and AXIOM_DATASET are correctly configured.

```bash
AXIOM_TOKEN="xaat-..."
AXIOM_DATASET="nextdevtpl"
```

--------------------------------

### Initialize Local Database Schema

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/en/quick-start.mdx

Push the current Drizzle schema to initialize a new local database. Use migrations for shared or production databases.

```bash
pnpm db:push
```

```bash
pnpm db:generate
pnpm db:migrate
```

--------------------------------

### Generate Migration File

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/en/database.mdx

Run this command after modifying `src/db/schema.ts` to create a new migration file. This file will be reviewed before deployment.

```bash
pnpm db:generate
```

--------------------------------

### Required Environment Variables for Local Boot

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/en/configuration.mdx

Set these environment variables to ensure a successful local boot. They are essential for database connection, authentication secrets, and callback URLs.

```bash
DATABASE_URL="postgresql://postgres:password@localhost:5432/nextdevtpl"
BETTER_AUTH_SECRET="replace-with-a-random-secret"
BETTER_AUTH_URL="http://localhost:3000"
```

--------------------------------

### PSEO Data File

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/en/customization.mdx

Configuration file for PSEO data.

```txt
src/features/pseo/data/pseo-pages.json
```

--------------------------------

### Home Route Configuration

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/en/customization.mdx

The home route for the marketing pages is defined here.

```txt
src/app/[locale]/(marketing)/page.tsx
```

--------------------------------

### Marketing Copy Location

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/en/customization.mdx

Find marketing copy for different locales in these JSON files.

```txt
messages/en.json
```

```txt
messages/zh.json
```

--------------------------------

### Server Component 翻译

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/zh/internationalization.mdx

在服务端组件中使用 next-intl 的服务端 helpers 来获取翻译后的文本。

```typescript
import { useTranslations } from 'next-intl';

export default function Greeting() {
  const t = useTranslations('Greeting');
  return (
    <>
      <p>{t('hello')}</p>
      <p>{t('welcome')}</p>
    </>
  );
}
```

--------------------------------

### Run Storage Security Tests

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/en/storage.mdx

Execute storage security tests using pnpm. Ensure this is run after any changes to upload rules.

```bash
pnpm test:run src/test/storage
```

--------------------------------

### Content Directory Structure

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/en/customization.mdx

Locations for different types of content like docs, blog, and legal.

```txt
src/content/docs/<locale>
```

```txt
src/content/blog/<locale>
```

```txt
src/content/legal/<locale>
```

--------------------------------

### Marketing Sections Location

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/en/customization.mdx

Locate marketing-related components within this directory.

```txt
src/features/marketing/components
```

--------------------------------

### Production Environment Variables

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/en/deployment.mdx

Essential environment variables for the production environment. Includes database connection, authentication secret, and application URL. Additional variables for optional services can also be added.

```bash
DATABASE_URL="postgresql://..."
BETTER_AUTH_SECRET="strong-production-secret"
BETTER_AUTH_URL="https://your-domain.com"
```

--------------------------------

### Apply Committed Migrations

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/en/database.mdx

Use this command to apply migration files that have been committed. This is typically done before deploying changes to production or staging environments.

```bash
pnpm db:migrate
```

--------------------------------

### 应用路由结构

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/zh/project-structure.mdx

展示了 Next.js 应用的路由目录结构，包括国际化处理、不同用户角色的路由分组以及 API 路由。

```txt
src/app/
├── [locale]/
│   ├── (marketing)/     # 首页、博客、法律页面、PSEO 等公开页面
│   ├── (auth)/          # 登录、注册、找回密码
│   ├── (dashboard)/     # 登录后的用户工作台
│   ├── (admin)/         # 管理员后台
│   └── docs/            # Fumadocs 文档
└── api/                 # Route handlers 和 webhooks
```

--------------------------------

### Application Routes Structure

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/en/project-structure.mdx

Defines the directory structure for application routes, including locale-specific segments, marketing, authentication, dashboard, admin areas, documentation, and API routes. The locale segment is managed by `next-intl`.

```txt
src/app/
├── [locale]/
│   ├── (marketing)/     # Home, blog, legal, PSEO, public pages
│   ├── (auth)/          # Sign in, sign up, password reset
│   ├── (dashboard)/     # Authenticated customer dashboard
│   ├── (admin)/         # Admin-only area
│   └── docs/            # Fumadocs documentation
└── api/                 # Route handlers and webhooks
```

--------------------------------

### Promote User to Admin

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/en/authentication.mdx

Update a user's role to 'admin' in the database using a SQL query. This is typically done after creating a local user.

```sql
update "user"
set role = 'admin'
where email = 'you@example.com';
```

--------------------------------

### Upstash Redis Environment Variables for Rate Limiting

Source: https://github.com/evepupil/nextdevtpl/blob/master/src/content/docs/en/observability.mdx

Set these environment variables to configure rate limiting using Upstash Redis. If Redis is not configured, development can continue without a startup failure.

```bash
UPSTASH_REDIS_REST_URL="https://..."
UPSTASH_REDIS_REST_TOKEN="..."
```