or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-interface.mdhelper-utilities.mdindex.mdproject-creation.mdtemplate-system.md
tile.json

template-system.mddocs/

Template System

Built-in template system providing pre-configured Next.js project structures for different use cases, with support for TypeScript/JavaScript and various styling and linting options.

Capabilities

Template Installation

Core function for installing Next.js templates with specified configuration options.

/**
 * Install a Next.js template with specified configuration
 * @param args - Template installation configuration
 */
async function installTemplate(args: InstallTemplateArgs): Promise<void>;

interface InstallTemplateArgs {
  /** Application name for package.json */
  appName: string;
  /** Target directory path */
  root: string;
  /** Package manager to use */
  packageManager: PackageManager;
  /** Internet connectivity status */
  isOnline: boolean;
  /** Template type to install */
  template: TemplateType;
  /** Language mode (TypeScript or JavaScript) */
  mode: TemplateMode;
  /** Enable ESLint configuration */
  eslint: boolean;
  /** Enable Biome configuration */
  biome: boolean;
  /** Enable Tailwind CSS configuration */
  tailwind: boolean;
  /** Use src/ directory structure */
  srcDir: boolean;
  /** Custom import alias pattern */
  importAlias: string;
  /** Skip package installation */
  skipInstall: boolean;
  /** Enable Turbopack for development */
  turbopack: boolean;
  /** Use Rspack as bundler */
  rspack: boolean;
}

Usage Examples:

The installTemplate function is used internally by the CLI to install pre-built Next.js templates with the user's selected configuration options.

Template Types

Available template configurations covering different Next.js project structures.

type TemplateType = 
  | "app"              // App Router template
  | "app-api"          // API-only App Router template
  | "app-empty"        // Empty App Router template
  | "app-tw"           // App Router with Tailwind CSS
  | "app-tw-empty"     // Empty App Router with Tailwind CSS
  | "default"          // Pages Router template
  | "default-empty"    // Empty Pages Router template
  | "default-tw"       // Pages Router with Tailwind CSS
  | "default-tw-empty"; // Empty Pages Router with Tailwind CSS

type TemplateMode = "js" | "ts";

Template Selection Logic:

// Template determined by configuration options
const template = `${app ? 'app' : 'default'}${tailwind ? '-tw' : ''}${empty ? '-empty' : ''}`;
const mode = typescript ? 'ts' : 'js';

Template File Resolution

Function for resolving template file paths during installation.

/**
 * Get the file path for a template file
 * @param args - Template file resolution arguments
 * @returns Absolute path to template file
 */
function getTemplateFile(args: GetTemplateFileArgs): string;

interface GetTemplateFileArgs {
  /** Template type */
  template: TemplateType;
  /** Language mode */
  mode: TemplateMode;
  /** File name within template */
  file: string;
}

Usage Examples:

The getTemplateFile function is used internally to resolve template file paths during the installation process.

File Processing and Transformation

The template system performs several transformations during installation:

File Renaming:

  • gitignore → .gitignore
  • README-template.md → README.md

Configuration Files:

  • Updates tsconfig.json/jsconfig.json with import alias settings
  • Configures path mapping for src directory when enabled
  • Modifies next.config.ts/next.config.mjs for Rspack integration

Import Alias Processing:

  • Replaces @/ with custom import alias throughout project files
  • Updates configuration files and source code consistently
  • Excludes certain files (fonts, favicon, git files) from processing

Package.json Generation

The template system generates appropriate package.json files based on configuration.

Base Configuration:

{
  "name": "app-name",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build", 
    "start": "next start"
  },
  "dependencies": {
    "react": "19.1.0",
    "react-dom": "19.1.0",
    "next": "15.5.2"
  }
}

TypeScript Dependencies:

{
  "devDependencies": {
    "typescript": "^5",
    "@types/node": "^20",
    "@types/react": "^19",
    "@types/react-dom": "^19"
  }
}

Tailwind CSS Dependencies:

{
  "devDependencies": {
    "@tailwindcss/postcss": "^4",
    "tailwindcss": "^4"
  }
}

ESLint Dependencies:

{
  "scripts": {
    "lint": "eslint"
  },
  "devDependencies": {
    "eslint": "^9",
    "eslint-config-next": "15.5.2",
    "@eslint/eslintrc": "^3"
  }
}

Biome Dependencies:

{
  "scripts": {
    "lint": "biome check",
    "format": "biome format --write"
  },
  "devDependencies": {
    "@biomejs/biome": "2.2.0"
  }
}

Source Directory Organization

When srcDir option is enabled, the template system reorganizes project structure:

const SRC_DIR_NAMES = ["app", "pages", "styles"];

Reorganization Process:

  1. Creates src/ directory
  2. Moves app/, pages/, and styles/ directories into src/
  3. Updates file references to include src/ in paths
  4. Modifies configuration files for new structure

Special Template Features

API-Only Templates:

  • Removes React and React-DOM dependencies
  • Excludes React type definitions (except for route types)
  • Removes linting scripts
  • Focuses on API route functionality

Empty Templates:

  • Minimal file structure
  • Basic configuration only
  • No example pages or components

Turbopack Integration:

  • Modifies dev and build scripts to include --turbopack flag
  • Updates package.json scripts automatically

Rspack Integration:

  • Adds next-rspack dependency
  • Wraps next.config with withRspack() function
  • Maintains configuration compatibility