Project Creation

Core functionality for creating Next.js projects from templates or examples with comprehensive configuration support and error handling.

Capabilities

createApp Function

Main function that orchestrates the entire project creation process including validation, template installation, example downloading, and project setup.

/**
 * Create a new Next.js application with specified configuration
 * @param options - Configuration options for the new project
 * @throws DownloadError - When example download fails
 */
async function createApp(options: CreateAppOptions): Promise<void>;

interface CreateAppOptions {
  /** Target directory path for the new application */
  appPath: string;
  /** Package manager to use for dependency installation */
  packageManager: PackageManager;
  /** Example name from Next.js examples or GitHub URL */
  example?: string;
  /** Path within example repository for complex URLs */
  examplePath?: string;
  /** Enable TypeScript configuration */
  typescript: boolean;
  /** Enable Tailwind CSS configuration */
  tailwind: boolean;
  /** Enable ESLint configuration */
  eslint: boolean;
  /** Enable Biome configuration */
  biome: boolean;
  /** Use App Router instead of Pages Router */
  app: boolean;
  /** Organize code inside src/ directory */
  srcDir: boolean;
  /** Custom import alias pattern */
  importAlias: string;
  /** Skip package installation step */
  skipInstall: boolean;
  /** Create minimal empty project */
  empty: boolean;
  /** Create API-only project */
  api?: boolean;
  /** Enable Turbopack for development */
  turbopack: boolean;
  /** Use Rspack as bundler */
  rspack: boolean;
  /** Skip git repository initialization */
  disableGit?: boolean;
}

Usage Examples:

The createApp function is the core internal function that orchestrates the entire project creation process. It is called by the CLI after processing user inputs and prompts.

Project Validation

The creation process includes comprehensive validation steps before project setup.

Validation Steps:

1. Directory Validation: Checks if target directory is writable
2. Name Validation: Validates project name against npm naming rules
3. Folder Emptiness: Ensures target directory is empty or contains only allowed files
4. Example Validation: Verifies example exists when specified
5. Repository Access: Validates GitHub repository access for custom examples

Template vs Example Creation

The function supports two main creation modes:

Template Mode (Default):

• Uses built-in Next.js templates
• Applies configuration options (TypeScript, Tailwind, etc.)
• Generates package.json with appropriate dependencies
• Sets up project structure based on options

Example Mode:

• Downloads from Next.js examples or custom GitHub repositories
• Preserves example structure while applying basic configuration
• Copies .gitignore and TypeScript definitions as needed
• Installs existing dependencies from example

Error Handling

/**
 * Custom error class for download failures
 */
class DownloadError extends Error {
  constructor(message: string);
}

Error Scenarios:

• Network Issues: Example download failures due to connectivity
• Repository Access: GitHub repository not found or inaccessible
• Permission Issues: Target directory not writable
• Validation Failures: Invalid project name or conflicting files

Error Handling Examples:

The CLI automatically handles DownloadError exceptions by offering users the option to fall back to the default template when example downloads fail.

Post-Creation Setup

After successful project creation, the function performs additional setup:

Git Initialization:

• Initializes git repository (unless disabled)
• Creates initial commit with "Initial commit from Create Next App"
• Sets up main branch if no default branch configured

Success Output:

• Displays success message with project location
• Shows available npm/yarn/pnpm scripts
• Provides next steps for running the development server

Example Output:

Success! Created my-next-app at /path/to/my-next-app
Inside that directory, you can run several commands:

  npm run dev
    Starts the development server.

  npm run build
    Builds the app for production.

  npm start
    Runs the built app in production mode.

We suggest that you begin by typing:

  cd my-next-app
  npm run dev

Configuration Processing

The function processes configuration options to determine the appropriate template and settings:

Template Selection Logic:

const template: TemplateType = `${app ? 'app' : 'default'}${tailwind ? '-tw' : ''}${empty ? '-empty' : ''}`;

Mode Selection:

const mode: TemplateMode = typescript ? 'ts' : 'js';

Special Cases:

• API-only projects use 'app-api' template regardless of other options
• Rspack configuration modifies next.config file post-installation
• Source directory setup moves app/pages directories into src/