create-flink-app

The easiest way to bootstrap a new Flink application. Creates a new project with a complete folder structure, sample handlers, schemas, repositories, and all necessary configuration files.

Inspired by create-next-app ❤️

Quick Start

Create a new Flink application in one command:

npx create-flink-app my-app

Then navigate to your app and start developing:

cd my-app
npm install
npm run dev

What's Included

The generated project includes:

Project Structure

my-app/
├── src/
│   ├── handlers/          # HTTP request handlers
│   │   └── car/
│   │       ├── GetCarById.ts
│   │       └── PostCar.ts
│   ├── repos/             # MongoDB repositories
│   │   └── CarRepo.ts
│   ├── schemas/           # TypeScript schemas
│   │   └── Car.ts
│   ├── ApplicationContext.ts  # App context definition
│   └── index.ts           # Application entry point
├── package.json
├── tsconfig.json
├── tsconfig.dist.json
└── .gitignore

Sample Code

• Handlers: Example GET and POST handlers with proper routing
• Repository: Sample MongoDB repository extending FlinkRepo
• Schemas: TypeScript interfaces for request/response validation
• Context: Pre-configured application context with dependency injection

Configuration Files

• TypeScript: Development and distribution configs
• Package.json: Pre-configured scripts and dependencies
• Git: Sensible .gitignore for Node.js projects

Usage

Create a New App

# Create app in current directory
npx create-flink-app .

# Create app in a new directory
npx create-flink-app my-app

# Create app with a specific name
npx create-flink-app my-awesome-api

Development Workflow

After creating your app:

# Install dependencies
npm install

# Start development server with hot reload
npm run dev

# Build for production
npm run build

# Run tests
npm test

What Gets Generated

1. Application Entry Point (src/index.ts)

import { FlinkApp } from "@flink-app/flink";
import AppContext from "./ApplicationContext";

async function start() {
    await new FlinkApp<AppContext>({
        name: "My App",
        db: {
            uri: "mongodb://localhost:27017/my-app",
        },
        plugins: [],
    }).start();
}

start();

2. Sample Handler (src/handlers/car/GetCarById.ts)

import { GetHandler, RouteProps } from "@flink-app/flink";
import AppContext from "../../ApplicationContext";
import Car from "../../schemas/Car";

export const Route: RouteProps = {
    path: "/car/:id",
};

type Parameters = {
    id: string;
};

const GetCarById: GetHandler<AppContext, Car, Parameters> = async ({ ctx, req }) => {
    const car = await ctx.repos.carRepo.getById(req.params.id);

    if (!car) {
        return {
            status: 404,
            data: null,
        };
    }

    return {
        status: 200,
        data: car,
    };
};

export default GetCarById;

3. Sample Repository (src/repos/CarRepo.ts)

import { FlinkRepo } from "@flink-app/flink";
import ApplicationContext from "../ApplicationContext";
import Car from "../schemas/Car";

class CarRepo extends FlinkRepo<ApplicationContext, Car> {}

export default CarRepo;

4. Application Context (src/ApplicationContext.ts)

import { FlinkContext } from "@flink-app/flink";
import CarRepo from "./repos/CarRepo";

interface ApplicationContext extends FlinkContext {
    repos: {
        carRepo: CarRepo;
    };
}

export default ApplicationContext;

Next Steps

After creating your app, you can:

1. Add more handlers: Create new files in src/handlers/
2. Define schemas: Add TypeScript interfaces in src/schemas/
3. Add repositories: Create new repo classes in src/repos/
4. Install plugins: Add official Flink plugins for common functionality
5. Configure database: Update MongoDB connection string in src/index.ts

Scaffolding Additional Code

Use flink-scaffold to quickly generate new handlers and repositories:

# Interactive scaffolding
npx flink-scaffold

# This will prompt you to create:
# - Individual handlers with schemas
# - Complete CRUD repositories with handlers

Available Scripts

The generated project includes these npm scripts:

• npm run dev: Start development server with nodemon and hot reload
• npm run build: Compile TypeScript to JavaScript
• npm test: Run Jasmine tests
• npm run test:watch: Run tests in watch mode
• npm start: Run the compiled application

Requirements

• Node.js 14 or higher
• MongoDB (if using database features)
• npm or yarn

Configuration

TypeScript

The project includes two TypeScript configurations:

• tsconfig.json: For development with tests
• tsconfig.dist.json: For production builds (excludes tests)

MongoDB

Configure your database connection in src/index.ts:

db: {
    uri: process.env.MONGODB_URI || "mongodb://localhost:27017/my-app",
}

Environment Variables

Create a .env file for environment-specific configuration:

PORT=3333
MONGODB_URI=mongodb://localhost:27017/my-app
NODE_ENV=development

Adding Plugins

Enhance your application with official Flink plugins:

# Install plugins
npm install @flink-app/jwt-auth-plugin @flink-app/s3-plugin

# Configure in src/index.ts
import { jwtAuthPlugin } from "@flink-app/jwt-auth-plugin";
import { s3Plugin } from "@flink-app/s3-plugin";

new FlinkApp<AppContext>({
    name: "My App",
    plugins: [
        jwtAuthPlugin({ /* config */ }),
        s3Plugin({ /* config */ }),
    ],
}).start();

Template Source

This tool generates projects based on the official Flink template, which includes best practices and recommended project structure for Flink applications.

Troubleshooting

Permission Issues

If you get permission errors, try:

npx --yes create-flink-app my-app

Template Errors

If the template fails to download, you can:

1. Check your internet connection
2. Try again with --force flag (if available)
3. Clone the template manually from the Flink repository

Related Tools

• flink-scaffold: Interactive code generator for handlers and repositories
• Flink Framework: Core Flink framework
• Flink Plugins: Official plugins for common functionality

License

MIT

Support

For issues and questions:

• GitHub Issues: Flink Framework Issues
• Documentation: Check the main Flink README