tessl/npm-projen

CDK for software projects - synthesizes configuration files from well-typed JavaScript/TypeScript definitions.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Web Projects

Name: tessl/npm-projen
Author: tessl

React and Next.js projects with modern web development tooling. Provides comprehensive setup for frontend applications with build systems, testing, and deployment.

Capabilities

ReactProject Class

React application project with modern frontend tooling and build systems.

/**
 * React application project with modern frontend tooling
 * Extends NodeProject with React-specific configuration
 */
class ReactProject extends NodeProject {
  constructor(options: ReactProjectOptions);
  
  /** Tailwind CSS integration (if enabled) */
  readonly tailwind?: Tailwind;
  /** PostCSS configuration (if enabled) */
  readonly postcss?: PostCSS;
  /** React version */
  readonly reactVersion: string;
}

interface ReactProjectOptions extends NodeProjectOptions {
  /** React version (default: "18.x") */
  reactVersion?: string;
  /** TypeScript support */
  typescript?: boolean;
  /** Enable Tailwind CSS */
  tailwind?: boolean;
  /** Tailwind CSS options */
  tailwindOptions?: TailwindOptions;
  /** Enable PostCSS */
  postcss?: boolean;
  /** PostCSS options */
  postcssOptions?: PostCSSOptions;
  /** Build tool (webpack, vite, etc.) */
  buildTool?: "webpack" | "vite" | "esbuild";
}

Basic React Project Example:

import { ReactProject } from "projen";

const project = new ReactProject({
  name: "my-react-app",
  defaultReleaseBranch: "main",
  
  // React configuration
  reactVersion: "18.2.0",
  typescript: true,
  
  // Styling
  tailwind: true,
  postcss: true,
  
  // Dependencies
  deps: [
    "react-router-dom@^6.8.0",
    "axios@^1.3.0",
  ],
  devDeps: [
    "@types/react",
    "@types/react-dom",
    "@testing-library/react",
    "@testing-library/jest-dom",
  ],
  
  // Build tool
  buildTool: "vite",
  
  // Testing
  jest: true,
  eslint: true,
  prettier: true,
});

NextJsProject Class

Next.js application with server-side rendering and modern React features.

/**
 * Next.js application project
 * React framework with server-side rendering and static generation
 */
class NextJsProject extends NodeProject {
  constructor(options: NextJsProjectOptions);
  
  /** Next.js version */
  readonly nextVersion: string;
  /** Tailwind CSS integration (if enabled) */
  readonly tailwind?: Tailwind;
  /** PostCSS configuration (if enabled) */
  readonly postcss?: PostCSS;
}

interface NextJsProjectOptions extends NodeProjectOptions {
  /** Next.js version (default: "13.x") */
  nextVersion?: string;
  /** TypeScript support */
  typescript?: boolean;
  /** Enable Tailwind CSS */
  tailwind?: boolean;
  /** Tailwind CSS options */
  tailwindOptions?: TailwindOptions;
  /** Enable PostCSS */
  postcss?: boolean;
  /** PostCSS options */
  postcssOptions?: PostCSSOptions;
  /** App directory (Next.js 13+) */
  appDir?: boolean;
  /** Source directory */
  srcDir?: boolean;
}

Next.js Project Example:

import { NextJsProject } from "projen";

const project = new NextJsProject({
  name: "my-nextjs-app",
  defaultReleaseBranch: "main",
  
  // Next.js configuration
  nextVersion: "13.4.0",
  typescript: true,
  appDir: true,
  srcDir: true,
  
  // Styling
  tailwind: true,
  postcss: true,
  
  // Dependencies
  deps: [
    "@next/font",
    "next-auth@^4.20.0",
    "prisma@^4.11.0",
  ],
  devDeps: [
    "@types/react",
    "@types/react-dom",
    "@types/node",
  ],
  
  // Testing
  jest: true,
  eslint: true,
  prettier: true,
});

// Add Next.js specific scripts
project.package.addScript("dev", "next dev");
project.package.addScript("build", "next build");
project.package.addScript("start", "next start");
project.package.addScript("lint", "next lint");

Tailwind CSS Integration

Tailwind CSS utility framework setup for web projects.

/**
 * Tailwind CSS utility framework setup
 * Provides utility-first CSS framework integration
 */
class Tailwind extends Component {
  constructor(project: NodeProject, options?: TailwindOptions);
  
  /** Tailwind configuration file */
  readonly config: any;
  /** PostCSS integration */
  readonly postcss?: PostCSS;
}

interface TailwindOptions {
  /** Tailwind CSS version */
  version?: string;
  /** Content paths for purging */
  content?: string[];
  /** Tailwind theme customization */
  theme?: Record<string, any>;
  /** Tailwind plugins */
  plugins?: string[];
  /** Enable JIT mode */
  jit?: boolean;
}

Tailwind Configuration Example:

import { ReactProject } from "projen";

const project = new ReactProject({
  name: "tailwind-app",
  tailwind: true,
  tailwindOptions: {
    content: [
      "./src/**/*.{js,jsx,ts,tsx}",
      "./public/index.html",
    ],
    theme: {
      extend: {
        colors: {
          primary: {
            50: "#eff6ff",
            500: "#3b82f6",
            900: "#1e3a8a",
          },
        },
        fontFamily: {
          sans: ["Inter", "sans-serif"],
        },
      },
    },
    plugins: [
      "@tailwindcss/forms",
      "@tailwindcss/typography",
    ],
  },
});

PostCSS Configuration

PostCSS processing setup for CSS transformation and optimization.

/**
 * PostCSS configuration for CSS processing
 * Handles CSS transformations, autoprefixing, and optimization
 */
class PostCSS extends Component {
  constructor(project: NodeProject, options?: PostCSSOptions);
  
  /** PostCSS configuration */
  readonly config: any;
  
  /** Add PostCSS plugin */
  addPlugin(plugin: string, options?: any): void;
}

interface PostCSSOptions {
  /** PostCSS plugins */
  plugins?: Record<string, any>;
  /** Enable autoprefixer */
  autoprefixer?: boolean;
  /** Enable cssnano for production */
  cssnano?: boolean;
}

TypeScript React Configuration

TypeScript configuration optimized for React projects.

/**
 * TypeScript React project configuration
 * Extends TypeScriptProject with React-specific settings
 */
class ReactTypescriptProject extends TypeScriptProject {
  constructor(options: ReactTypescriptProjectOptions);
  
  /** React version */
  readonly reactVersion: string;
  /** JSX configuration */
  readonly jsxFactory?: string;
}

interface ReactTypescriptProjectOptions extends TypeScriptProjectOptions {
  /** React version */
  reactVersion?: string;
  /** JSX factory function */
  jsxFactory?: string;
  /** JSX fragment factory */
  jsxFragmentFactory?: string;
  /** JSX import source */
  jsxImportSource?: string;
}

Complete Web Project Example:

import { NextJsProject } from "projen";

const project = new NextJsProject({
  name: "advanced-nextjs-app",
  defaultReleaseBranch: "main",
  
  // Next.js configuration
  nextVersion: "13.4.0",
  typescript: true,
  appDir: true,
  srcDir: true,
  
  // Project metadata
  description: "Advanced Next.js application with full-stack features",
  author: "Frontend Developer",
  authorEmail: "frontend@example.com",
  
  // Styling
  tailwind: true,
  tailwindOptions: {
    content: [
      "./src/**/*.{js,ts,jsx,tsx,mdx}",
      "./app/**/*.{js,ts,jsx,tsx,mdx}",
    ],
    theme: {
      extend: {
        colors: {
          brand: {
            50: "#f0f9ff",
            500: "#0ea5e9",
            900: "#0c4a6e",
          },
        },
      },
    },
    plugins: [
      "@tailwindcss/forms",
      "@tailwindcss/typography",
      "@tailwindcss/aspect-ratio",
    ],
  },
  
  postcss: true,
  postcssOptions: {
    plugins: {
      "tailwindcss": {},
      "autoprefixer": {},
    },
  },
  
  // Frontend dependencies
  deps: [
    "@next/font",
    "next-auth@^4.20.0",
    "@prisma/client@^4.11.0",
    "react-hook-form@^7.43.0",
    "@hookform/resolvers@^2.9.0",
    "zod@^3.20.0",
    "framer-motion@^10.0.0",
    "lucide-react@^0.220.0",
  ],
  
  // Development dependencies
  devDeps: [
    "@types/react",
    "@types/react-dom", 
    "@types/node",
    "prisma@^4.11.0",
    "@tailwindcss/forms",
    "@tailwindcss/typography",
    "@tailwindcss/aspect-ratio",
    "autoprefixer",
    "postcss",
  ],
  
  // Testing setup
  jest: true,
  jestOptions: {
    testEnvironment: "jsdom",
    setupFilesAfterEnv: ["<rootDir>/jest.setup.js"],
    moduleNameMapping: {
      "^@/(.*)$": "<rootDir>/$1",
    },
  },
  
  // Code quality
  eslint: true,
  eslintOptions: {
    extends: ["next/core-web-vitals"],
    rules: {
      "@next/next/no-html-link-for-pages": "off",
    },
  },
  
  prettier: true,
  prettierOptions: {
    settings: {
      semi: true,
      singleQuote: false,
      tabWidth: 2,
      trailingComma: "es5",
    },
  },
});

// Add custom Next.js scripts
project.package.addScript("dev", "next dev");
project.package.addScript("build", "next build");
project.package.addScript("start", "next start");
project.package.addScript("lint", "next lint");
project.package.addScript("type-check", "tsc --noEmit");

// Database scripts
project.package.addScript("db:generate", "prisma generate");
project.package.addScript("db:push", "prisma db push");
project.package.addScript("db:migrate", "prisma migrate dev");
project.package.addScript("db:studio", "prisma studio");

// Add custom tasks
project.addTask("dev:full", {
  description: "Start development with database",
  exec: "npm run db:push && npm run dev",
});

project.addTask("build:analyze", {
  description: "Analyze bundle size",
  exec: "ANALYZE=true npm run build",
});

project.addTask("test:e2e", {
  description: "Run end-to-end tests",
  exec: "playwright test",
});

// Custom package.json fields
project.package.addField("engines", {
  node: ">=16.0.0",
  npm: ">=8.0.0",
});

// Environment configuration
project.package.addScript("env:example", "cp .env.example .env.local");

Storybook Integration

Storybook component development environment for React projects.

/**
 * Storybook integration for component development
 * Provides isolated component development and testing
 */
class Storybook extends Component {
  constructor(project: ReactProject, options?: StorybookOptions);
  
  /** Storybook version */
  readonly version: string;
  /** Storybook configuration directory */
  readonly configDir: string;
}

interface StorybookOptions {
  /** Storybook version */
  version?: string;
  /** Storybook addons */
  addons?: string[];
  /** Stories directory pattern */
  stories?: string[];
  /** Static directory */
  staticDirs?: string[];
}

Types

Web-Specific Types

interface TailwindConfig {
  content: string[];
  theme?: {
    extend?: Record<string, any>;
    colors?: Record<string, any>;
    fontFamily?: Record<string, string[]>;
    spacing?: Record<string, string>;
  };
  plugins?: string[];
  darkMode?: "media" | "class" | ["class", string];
}

interface NextConfig {
  /** Experimental features */
  experimental?: {
    appDir?: boolean;
    serverComponentsExternalPackages?: string[];
  };
  /** Image optimization */
  images?: {
    domains?: string[];
    formats?: string[];
  };
  /** Environment variables */
  env?: Record<string, string>;
  /** Redirects */
  redirects?: () => Promise<Array<{
    source: string;
    destination: string;
    permanent: boolean;
  }>>;
}

interface PostCSSConfig {
  plugins: Record<string, any>;
  parser?: string;
  syntax?: string;
}

interface ReactTestingOptions {
  /** Testing library version */
  testingLibraryVersion?: string;
  /** Jest DOM version */
  jestDomVersion?: string;
  /** MSW for API mocking */
  msw?: boolean;
  /** Playwright for E2E testing */
  playwright?: boolean;
}

Install with Tessl CLI