API Reference

Programmatic usage and API documentation for integrating Kickstart Express into your tools and workflows.

Node.js API

While Kickstart Express is primarily a CLI tool, you can also use it programmatically in Node.js applications.

Installation

npm install kickstart-express

Basic Usage

const { generateProject } = require('kickstart-express');

// Generate a project programmatically
await generateProject({
  name: 'my-api',
  language: 'ts',
  docker: true,
  src: true,
  structured: true,
  outputDir: './projects'
});

Configuration Object

The configuration object used for programmatic project generation.

ProjectConfig Interface

interface ProjectConfig {
  name: string;                    // Project name (required)
  language: 'ts' | 'js';          // Programming language
  docker?: boolean;               // Include Docker files
  src?: boolean;                  // Use src folder structure
  structured?: boolean;           // Use structured architecture
  outputDir?: string;             // Output directory (default: current)
  packageManager?: 'npm' | 'pnpm' | 'yarn'; // Package manager
  installDependencies?: boolean;  // Auto-install dependencies
}

Configuration Properties

name

Type: string (required)
Description: The name of the project. Used as directory name and in package.json.

language

Type: 'ts' | 'js'
Default: 'ts'
Description: Programming language for the project.

docker

Type: boolean
Default: false
Description: Include Dockerfile and docker-compose.yml files.

src

Type: boolean
Default: false
Description: Create src folder structure instead of root-level files.

structured

Type: boolean
Default: false
Description: Use structured architecture with controllers, services, routes. Automatically enables src.

outputDir

Type: string
Default: process.cwd()
Description: Directory where the project will be created.

packageManager

Type: 'npm' | 'pnpm' | 'yarn'
Default: 'pnpm'
Description: Package manager to use for dependency installation.

installDependencies

Type: boolean
Default: true
Description: Automatically install dependencies after project generation.

API Methods

generateProject()

Main method to generate a new Express.js project.

async function generateProject(config: ProjectConfig): Promise<GenerationResult>

Parameters:

config - ProjectConfig object with project configuration

Returns:

Promise<GenerationResult>

interface GenerationResult {
  success: boolean;
  projectPath: string;
  message: string;
  error?: string;
}

Example:

const result = await generateProject({ name: 'my-awesome-api', language: 'ts', docker: true, structured: true }); if (result.success) { console.log(`Project created at: ${result.projectPath}`); } else { console.error(`Error: ${result.error}`); }

validateConfig()

Validate a project configuration before generation.

function validateConfig(config: Partial<ProjectConfig>): ValidationResult

Returns:

interface ValidationResult {
  valid: boolean;
  errors: string[];
  warnings: string[];
}

Example:

const validation = validateConfig({
  name: 'my-api',
  language: 'ts'
});

if (!validation.valid) {
  console.error('Configuration errors:', validation.errors);
}

getTemplateInfo()

Get information about available templates and their features.

function getTemplateInfo(): TemplateInfo[]

interface TemplateInfo {
  name: string;
  description: string;
  features: string[];
  language: 'ts' | 'js' | 'both';
  complexity: 'simple' | 'medium' | 'advanced';
}

Integration Examples

Build Tool Integration

Integrate with build tools like Gulp, Webpack, or custom scripts.

// gulpfile.js const { generateProject } = require('kickstart-express'); gulp.task('create-service', async () => { const serviceName = process.env.SERVICE_NAME || 'new-service'; await generateProject({ name: serviceName, language: 'ts', docker: true, structured: true, outputDir: './services' }); console.log(`Service ${serviceName} created!`); });

CI/CD Pipeline

Use in continuous integration pipelines for automated project creation.

// create-service.js const { generateProject } = require('kickstart-express'); async function createService() { const config = { name: process.argv[2], language: 'ts', docker: true, structured: true, outputDir: process.env.SERVICES_DIR || './services' }; try { const result = await generateProject(config); if (result.success) { console.log(`✅ Service created: ${result.projectPath}`); process.exit(0); } else { console.error(`❌ Failed: ${result.error}`); process.exit(1); } } catch (error) { console.error('Unexpected error:', error); process.exit(1); } } createService();

Custom CLI Tool

Build your own CLI tool on top of Kickstart Express.

#!/usr/bin/env node
const { generateProject, validateConfig } = require('kickstart-express');
const { program } = require('commander');

program
  .command('api <name>')
  .description('Create a new API service')
  .option('--lang <language>', 'Programming language', 'ts')
  .option('--no-docker', 'Skip Docker configuration')
  .action(async (name, options) => {
    const config = {
      name,
      language: options.lang,
      docker: options.docker,
      structured: true,
      src: true
    };

    const validation = validateConfig(config);
    if (!validation.valid) {
      console.error('Invalid configuration:', validation.errors);
      return;
    }

    const result = await generateProject(config);
    console.log(result.message);
  });

program.parse();

Express.js Middleware

Create an endpoint in your existing Express app to generate new projects.

const express = require('express');
const { generateProject } = require('kickstart-express');

const app = express();
app.use(express.json());

app.post('/api/projects', async (req, res) => {
  try {
    const { name, language, features } = req.body;
    
    const config = {
      name,
      language: language || 'ts',
      docker: features?.includes('docker'),
      structured: features?.includes('structured'),
      outputDir: './generated-projects'
    };

    const result = await generateProject(config);
    
    if (result.success) {
      res.json({
        success: true,
        message: 'Project created successfully',
        path: result.projectPath
      });
    } else {
      res.status(400).json({
        success: false,
        error: result.error
      });
    }
  } catch (error) {
    res.status(500).json({
      success: false,
      error: 'Internal server error'
    });
  }
});

Error Handling

Common Errors

PROJECT_EXISTS

Project directory already exists

Error: Directory 'my-api' already exists

INVALID_NAME

Invalid project name format

Error: Project name must be a valid npm package name

PERMISSION_DENIED

Insufficient permissions to create project

Error: Permission denied writing to directory

DEPENDENCY_INSTALL_FAILED

Failed to install project dependencies

Error: Failed to install dependencies with pnpm

Error Handling Example

async function createProjectSafely(config) { try { // Validate configuration first const validation = validateConfig(config); if (!validation.valid) { throw new Error(`Invalid config: ${validation.errors.join(', ')}`); } // Check if project already exists const projectPath = path.join(config.outputDir || '.', config.name); if (fs.existsSync(projectPath)) { throw new Error(`Project '${config.name}' already exists`); } // Generate project const result = await generateProject(config); if (!result.success) { throw new Error(result.error); } return result; } catch (error) { console.error('Failed to create project:', error.message); // Cleanup on failure if (fs.existsSync(projectPath)) { fs.removeSync(projectPath); } throw error; } }

TypeScript Support

Kickstart Express includes full TypeScript definitions for type-safe development.

Type Definitions

// Install types (included automatically)
npm install @types/kickstart-express

// Import with full type support
import { 
  generateProject, 
  validateConfig, 
  ProjectConfig, 
  GenerationResult 
} from 'kickstart-express';

// Type-safe configuration
const config: ProjectConfig = {
  name: 'typed-api',
  language: 'ts',
  docker: true,
  structured: true
};

// Type-safe result handling
const result: GenerationResult = await generateProject(config);