Core Concepts

Learn the fundamental building blocks of CanxJS applications. Master these concepts to build powerful, scalable APIs.

Modules (Auto-Scan)

Organize your application structure with smart, auto-scanning modules.

The Module Decorator

Modules organize components, controllers, and services into cohesive blocks.

TypeScript

@Module({
  controllers: [UserController],
  providers: [UserService],
  exports: [UserService]
})
export class UserModule {}

Auto-Scanning (New 🚀)

Automatically discover and register modules without manual imports using Bun.Glob.

TypeScript

// In your main entry file
import { Module } from 'canxjs';

// Automatically finds and registers all modules in ./src
await Module.scan('./src');

Routing

Define and manage application routes with a powerful, intuitive API.

Basic Routes

Define routes using HTTP method helpers like app.get(), app.post(), app.put(), and app.delete().

TypeScript

app.get("/users", (req, res) => {
  res.json({ users: [] });
});

app.post("/users", (req, res) => {
  const user = req.body;
  res.json({ created: user });
});

Route Parameters

Capture dynamic values from URLs using colon syntax.

TypeScript

app.get("/users/:id", (req, res) => {
  const { id } = req.params;
  res.json({ userId: id });
});

Route Groups

Organize routes with prefixes and shared middleware.

TypeScript

app.group("/api/v1", (router) => {
  router.get("/users", getUsers);
  router.get("/posts", getPosts);
});

Controllers

Organize request handling logic into reusable controller classes.

Controller Classes

Create controller classes to group related route handlers.

TypeScript

export class UserController {
  async index(req: Request, res: Response) {
    const users = await User.all();
    res.json(users);
  }

  async show(req: Request, res: Response) {
    const user = await User.find(req.params.id);
    res.json(user);
  }
}

Resource Controllers

Generate CRUD operations automatically with resource controllers.

TypeScript

// Registers: index, show, store, update, destroy
app.resource("/posts", PostController);

Middleware

Intercept and modify requests before they reach your route handlers.

Creating Middleware

Middleware functions receive request, response, and a next function.

TypeScript

const authMiddleware = async (req, res, next) => {
  const token = req.headers.authorization;
  
  if (!token) {
    return res.status(401).json({ error: "Unauthorized" });
  }
  
  req.user = await verifyToken(token);
  next();
};

Applying Middleware

Apply middleware globally, to route groups, or individual routes.

TypeScript

// Global middleware
app.use(logger());
app.use(cors());

// Route-specific
app.get("/admin", authMiddleware, adminHandler);

// Group middleware
app.group("/api", { middleware: [authMiddleware] }, (router) => {
  router.get("/profile", profileHandler);
});

Models & ORM

Query and manage your database with an elegant ORM.

Defining Models

Create model classes that map to database tables.

TypeScript

import { Model } from "canxjs/orm";

export class User extends Model {
  static table = "users";
  
  id!: number;
  name!: string;
  email!: string;
  createdAt!: Date;
}

Querying Data

Use the fluent query builder for database operations.

TypeScript

// Find all users
const users = await User.all();

// Find by ID
const user = await User.find(1);

// Query with conditions
const admins = await User.where("role", "admin")
  .orderBy("createdAt", "desc")
  .limit(10)
  .get();

Views & JSX

Build server-rendered views using familiar JSX syntax.

JSX Templates

Create views using JSX for type-safe, component-based templates.

TypeScript

// views/Home.tsx
export function Home({ title, users }) {
  return (
    <Layout title={title}>
      <h1>Welcome to {title}</h1>
      <ul>
        {users.map(user => (
          <li key={user.id}>{user.name}</li>
        ))}
      </ul>
    </Layout>
  );
}

Rendering Views

Render views from your controllers with data.

TypeScript

app.get("/", async (req, res) => {
  const users = await User.all();
  res.render(Home, { title: "My App", users });
});

Ready to dive deeper?

Explore the full API reference or follow our step-by-step tutorials.

export class UserController { async index(req: Request, res: Response) { const users = await User.all(); res.json(users); } async show(req: Request, res: Response) { const user = await User.find(req.params.id); res.json(user); } }

const authMiddleware = async (req, res, next) => { const token = req.headers.authorization; if (!token) { return res.status(401).json({ error: "Unauthorized" }); } req.user = await verifyToken(token); next(); };

// Global middleware app.use(logger()); app.use(cors()); // Route-specific app.get("/admin", authMiddleware, adminHandler); // Group middleware app.group("/api", { middleware: [authMiddleware] }, (router) => { router.get("/profile", profileHandler); });

// Find all users const users = await User.all(); // Find by ID const user = await User.find(1); // Query with conditions const admins = await User.where("role", "admin") .orderBy("createdAt", "desc") .limit(10) .get();

// views/Home.tsx export function Home({ title, users }) { return ( <Layout title={title}> <h1>Welcome to {title}</h1> <ul> {users.map(user => ( <li key={user.id}>{user.name}</li> ))} </ul> </Layout> ); }