Quick Start Guide

Welcome to the Igniter.js Quick Start Guide! This tutorial provides a detailed, step-by-step walkthrough to build your first fully type-safe API endpoint. We'll go from an empty directory to a running server, explaining each concept along the way.

Prerequisites

Before we begin, please ensure you have the following installed on your system:

• Node.js

  Version 18.x or higher.
• A Package Manager

  This guide provides commands for [object Object], [object Object], and [object Object].

Step 1: Create Your Igniter.js Project

We'll start by using the official igniter init command, which scaffolds a new, production-ready project with a logical folder structure and all necessary configurations.

Open your terminal and run the command below using your preferred package manager:

npx @igniter-js/cli init my-first-api

This command creates a new directory called my-first-api, installs dependencies, and sets up your project.

Once the process is complete, navigate into your new project directory:

cd my-first-api

Step 2: Create Your First Controller

In Igniter.js, a Controller is a file that groups related API endpoints. These endpoints are called Actions (either a Query for GET requests or a Mutation for POST, PUT, DELETE, etc.).

Let's create a "hello world" controller. First, create the necessary folders:

mkdir -p src/features/greeting/controllers

Now, create a new file at src/features/greeting/controllers/greeting.controller.ts and add the following code:

// src/features/greeting/controllers/greeting.controller.ts
import { igniter } from '@/igniter';
import { z } from 'zod';

export const greetingController = igniter.controller({
  name: 'GreetingController',
  path: '/greetings',
  actions: {
    hello: igniter.query({
      query: z.object({
        name: z.string().optional().default('World'),
      }),
      handler: ({ request, response }) => {
        const { name } = request.query;
        return response.success({ message: `Hello, ${name}!` });
      },
    }),
  },
});

Understanding the Code: A Properties Breakdown

To understand what we just wrote, you can expand the sections below to see a detailed breakdown of the properties for both the controller and the actions within it.

Step 3: Register the Controller with the Router

Your controller is ready, but the application doesn't know about it yet. We need to register it in the main router.

Open src/igniter.router.ts and modify it to include your new controller:

// src/igniter.router.ts
import { igniter } from '@/igniter';
// 1. Import your new controller
import { greetingController } from '@/features/greeting/controllers/greeting.controller';

export const AppRouter = igniter.router({
  controllers: {
    // 2. Register the controller under a key.
    // This key is used for client-side type inference.
    greetings: greetingController,
  },
});

// This export is crucial for client-side type safety!
export type AppRouterType = typeof AppRouter;

Step 4: Run the Development Server

Igniter.js includes an interactive development server that provides real-time feedback and a dashboard for your API.

Start the server by running the following command in your terminal:

npm run dev

This command executes igniter dev --interactive. You should see a dashboard in your terminal, confirming that the server is running successfully on http://localhost:3000.

Step 5: Test Your API Endpoint

Your API is now live and ready to be tested! You can use a tool like cURL or simply open the URL in your web browser.

Open a new terminal window and run this command:

# Test with the default name ('World')
curl http://localhost:3000/api/v1/greetings/hello

You should see the following JSON response:

{"message":"Hello, World!"}

Now, let's provide a custom name via the query string:

# Test with a custom name
curl "http://localhost:3000/api/v1/greetings/hello?name=Igniter"

And the response will be:

{"message":"Hello, Igniter!"}

Congratulations!

You have successfully built and tested your first fully type-safe API endpoint with Igniter.js!

In this guide, you have learned how to:

• Scaffold a project using igniter init.
• Create a Controller to group related API actions.
• Define a Query Action with input validation using Zod.
• Register the controller with the main application Router.
• Run the interactive development server and test your endpoint.

Ready for a Real Project?

You've learned the basics, now it's time to build something more substantial. Our official starter templates are the perfect way to kickstart your next project with a production-ready foundation.

Next.js Full-Stack App

A full-featured application built using the latest Next.js conventions with end-to-end type safety powered by Igniter.js.

Create Project

Bun + React Full-Stack App

A full-stack, type-safe application with Bun and React featuring server-side rendering and unified runtime.

Create Project

TanStack Start App

A modern full-stack application built with TanStack Start featuring type-safe routing and server functions.

Create Project

Express REST API

A robust REST API built with Express.js and Igniter.js featuring structured logging and background jobs.

Create Project

Bun REST API

A high-performance REST API built with Bun runtime and Igniter.js for maximum speed and efficiency.

Create Project

Deno REST API

A secure and modern REST API built with Deno runtime and Igniter.js featuring built-in TypeScript support.

Create Project

Next Steps

• Core Concepts

  Take a deep dive into the fundamental building blocks of the framework.
• Routing in Depth

  Learn more about file-based routing, parameters, and advanced routing techniques.
• Project Structure

  Understand our best practices for organizing large and scalable applications.