Igniter.js Starter: TanStack Start Full-Stack App

Welcome to the Igniter.js starter for building full-stack, type-safe applications with TanStack Start. This template provides a modern, performant foundation for web applications, combining the power of Vite, file-based routing with TanStack Router, and an end-to-end type-safe API layer provided by Igniter.js.

Features

• Full-Stack with TanStack Start

  A cohesive, modern full-stack framework powered by Vite.
• End-to-End Type Safety

  Powered by Igniter.js, ensuring type safety between your front-end and back-end.
• File-Based Routing

  Uses TanStack Router for intuitive, type-safe routing.
• Server-Side Data Fetching

  Leverages TanStack Router's loaders to fetch data on the server.
• Feature-Based API Architecture

  A scalable project structure that organizes API code by business domain.
• Ready-to-Use Services

  Pre-configured examples for: [object Object]
• Auto-Generated API Client

  A fully-typed client that mirrors your API, providing autocomplete and compile-time error checking.

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (v18 or higher)
• npm or a compatible package manager like Bun.
• A running Redis instance (for caching and background jobs).
• A PostgreSQL database (or you can configure Prisma for a different one).

Getting Started

Follow these steps to get your project up and running:

1. Clone the Repository

   Code

   git clone https://github.com/felipebarcelospro/igniter-js.git
   cd igniter-js/apps/starter-tanstack-start
   

2. Install Dependencies

   Code

   npm install
   

3. Configure Environment Variables Create a .env file in the root of this starter (igniter-js/apps/starter-tanstack-start/.env) and add your database and Redis connection URLs:

   Code

   # .env
   DATABASE_URL="postgresql://user:password@localhost:5432/mydatabase?schema=public"
   REDIS_URL="redis://127.0.0.1:6379"
   

4. Run Database Migrations

   Code

   npx prisma db push
   

5. Run the Development Server

   Code

   npm run dev
   

   This command starts the Vite development server. Your application will be available at http://localhost:5173.

How It Works

This starter integrates an Igniter.js API backend directly into a TanStack Start application.

1. API Integration via Catch-All Route

The connection point between TanStack Start and Igniter.js is a catch-all API route.

• Location

  [object Object]
• Mechanism

  This file uses [object Object] from TanStack Router to capture all requests made to [object Object]. Both the [object Object] (for GET requests) and [object Object] (for POST, PUT, etc.) functions call a handler that passes the standard [object Object] object directly to the [object Object] from Igniter.js. This seamlessly delegates API handling to the Igniter.js runtime.

2. The Igniter.js API Layer

The back-end API logic is defined purely within the Igniter.js structure.

• Initialization (src/igniter.ts)

  This is where the core Igniter instance is created and configured with adapters for the store (Redis), jobs (BullMQ), and logging.
• Router (src/igniter.router.ts)

  This file assembles the main API router by importing all feature controllers.
• Controllers (src/features/[feature]/controllers/)

  Controllers group related API actions ([object Object] and [object Object]). This is where your business logic lives.

3. Type-Safe Client & React Hooks

Igniter.js automatically generates a type-safe client based on your API router.

• The api object in src/igniter.client.ts is your gateway to the back-end.
• You can use the provided React hooks (.useQuery(), .useMutation()) in your components to fetch and mutate data with full type safety.

Example Client Component Usage:

// src/routes/index.tsx
'use client';
import { api } from '@/igniter.client';

export function Component() {
  const { data, isLoading } = api.example.health.useQuery();

  if (isLoading) return <div>Loading...</div>;

  return (
    <div>
      <h1>Welcome to TanStack Start!</h1>
      <p>API Status: {data?.status}</p>
    </div>
  );
}

Project Structure

The project combines TanStack Start's file-based routing with Igniter.js's feature-based API structure.

src/
├── components/           # Shared, reusable UI components
├── features/             # Business logic, grouped by feature
│   └── example/
│       └── controllers/  # API endpoint definitions
├── routes/               # TanStack Router: file-based routes
│   ├── api/
│   │   └── v1/
│   │       └── $.ts      # Igniter.js API catch-all entry point
│   ├── __root.tsx        # Root layout component
│   └── index.tsx         # Component for the '/' route
├── services/             # Service initializations (Redis, Prisma, etc.)
├── igniter.ts            # Igniter.js core instance
├── igniter.client.ts     # Auto-generated type-safe API client
├── igniter.router.ts     # Main API router
└── router.tsx            # TanStack Router setup

Available Scripts

• npm run dev: Starts the Vite development server.
• npm run build: Builds the application for production.
• npm run start: Starts the production server.

Further Learning

• Igniter.js GitHub Repository
• Igniter.js Documentation Wiki
• TanStack Start Documentation
• TanStack Router Documentation

License

This starter is licensed under the MIT License.