Skip to main content

Quick Start: TypeScript

Open Repo Download ZIP

git clone https://github.com/AEEF-AI/aeef-quickstart.git my-project

This guide walks through setting up the AEEF Quick Start tier for a TypeScript project. By the end, you will have a running Next.js application with AI tool configuration, linting, testing, security scanning, and CI -- all enforcing AEEF standards.

Prerequisites​

  • Node.js 22+ -- Required for ESLint flat config and modern ECMAScript features
  • npm 10+ -- Ships with Node.js 22
  • Git 2.30+ -- For branch protection and conventional commits
  • An AI coding tool configured for your IDE

Verify your environment:

node --version   # v22.x.x
npm --version    # 10.x.x
git --version    # 2.30+

Step-by-Step Setup​

1. Create the Project​

# Use the template
git clone https://github.com/AEEF-AI/aeef-quickstart.git my-ts-project
cd my-ts-project

# Run the TypeScript setup
./scripts/setup.sh --lang typescript

2. Install Dependencies​

npm install

This installs the application dependencies along with the dev tooling: ESLint, Jest, Semgrep (via npx), and TypeScript.

3. Verify the Configuration​

Run the full check suite to confirm everything passes on a clean install:

npm run check

This executes, in order: lint, typecheck, test, and security:scan.

File-by-File Walkthrough​

eslint.config.mjs -- ESLint Flat Config​

The ESLint configuration uses the flat config format (ESLint 9+) and enforces code quality rules aligned with PRD-STD-006:

import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';

export default tseslint.config(
  eslint.configs.recommended,
  ...tseslint.configs.strictTypeChecked,
  {
    rules: {
      'complexity': ['error', 10],
      'max-depth': ['error', 4],
      'max-lines-per-function': ['warn', 50],
      '@typescript-eslint/no-explicit-any': 'error',
      '@typescript-eslint/no-unused-vars': 'error',
    },
  },
);

jest.config.ts -- Test Configuration​

Jest is configured with an 80% coverage threshold across all metrics, enforcing PRD-STD-003:

export default {
  preset: 'ts-jest',
  testEnvironment: 'node',
  coverageThreshold: {
    global: {
      branches: 80,
      functions: 80,
      lines: 80,
      statements: 80,
    },
  },
  collectCoverageFrom: ['src/**/*.ts', '!src/**/*.d.ts'],
};

.cursorrules -- Cursor IDE Configuration​

This file instructs Cursor to follow AEEF prompt engineering discipline when generating code:

You are assisting on a project governed by AEEF Standards.
All AI-generated code MUST:
- Include a comment indicating AI assistance was used
- Follow the project's ESLint configuration
- Include unit tests for any new functions
- Never introduce dependencies without explicit approval
- Follow conventional commit message format

.github/copilot-instructions.md -- GitHub Copilot Rules​

Similar to .cursorrules but formatted for GitHub Copilot's custom instructions feature. Enforces the same prompt engineering standards through Copilot's interface.

.github/workflows/ci.yml -- CI Pipeline​

The GitHub Actions workflow runs on every pull request and push to main:

name: CI
on:
  pull_request:
  push:
    branches: [main]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm test -- --coverage
      - run: npx semgrep --config .semgrep/ src/
      - run: npm audit --audit-level=high

.semgrep/ -- Security Rules​

The Semgrep directory contains custom rules targeting common AI-generated code vulnerabilities:

  • ai-code-patterns.yml -- Detects patterns commonly introduced by AI tools (hardcoded secrets, overly permissive CORS, unvalidated input)
  • typescript-security.yml -- TypeScript-specific rules (prototype pollution, eval usage, unsafe type assertions)

Running the Example Application​

# Development server
npm run dev

# Build for production
npm run build

# Start production server
npm start

The example application is a minimal Next.js API with health check and user endpoints, demonstrating AEEF-compliant patterns for input validation, error handling, and test coverage.

Making Your First AI-Assisted PR​

  1. Create a feature branch:

    git checkout -b feat/add-user-validation

  2. Use your AI tool to generate a new endpoint or utility function.

  3. Ensure the generated code has test coverage:

    npm test -- --coverage

  4. Run the full quality suite:

    npm run check

  5. Commit and push:

    git add .
    git commit -m "feat: add user input validation with zod schema"
    git push -u origin feat/add-user-validation

  6. Open a PR and fill in the AEEF PR template, including the AI-disclosure section.

Running Security Scans Locally​

# Semgrep SAST scan
npx semgrep --config .semgrep/ src/

# Dependency vulnerability audit
npm audit --audit-level=high

# Check for known vulnerable packages
npx better-npm-audit audit

Next Steps​

  • Add more standards? Upgrade to Transformation: TypeScript for mutation testing, metrics, and agent SDLC.
  • Existing project? Copy individual configs from the Config Packs page.
  • Different language? See the Python or Go Quick Start guides.
Last updated on by BalrogEg