Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/juanjh1/asimilation/llms.txt

Use this file to discover all available pages before exploring further.

​
Install Asimilation

First, install the framework using your preferred package manager: 
npm install @asimilation/core

​
Create Your First Server

1

Create the server file

Create a new file server.ts in your project:
server.ts
import { asi, url } from '@asimilation/core';

asi.setup(3000, import.meta.url);

url.addPath("/", (req, res) => {
  res.sendJson({ message: "Hello, Asimilation!" }, 200);
});

asi.run();
The import.meta.url parameter is required for module resolution. Always pass it as the second argument to asi.setup().
2

Build and run

If you’re using TypeScript, compile your code first:
npx tsc server.ts
node server.js
Or use tsx for development:
npx tsx server.ts
You should see your server start on port 3000.
3

Test the endpoint

Open a new terminal and test your endpoint:
curl http://localhost:3000/
You should receive:
{"message": "Hello, Asimilation!"}

​
Add Dynamic Routes

Now let’s add routes with dynamic parameters:
server.ts
import { asi, url } from '@asimilation/core';

asi.setup(3000, import.meta.url);

// Static route
url.addPath("/", (req, res) => {
  res.sendJson({ message: "Welcome to the API" }, 200);
});

// Dynamic route with integer parameter
url.addPath("/<int:id>", (req, res) => {
  const userId = req.params.id;
  res.sendJson({ 
    message: `User ID: ${userId}`,
    id: userId 
  }, 200);
});

// Dynamic route with slug parameter
url.addPath("/posts/<slug:slug>", (req, res) => {
  const postSlug = req.params.slug;
  res.sendJson({ 
    message: `Post slug: ${postSlug}`,
    slug: postSlug 
  }, 200);
});

asi.run();
Asimilation supports Django-style URL patterns:
  • <int:name> - Matches integers only
  • <string:name> - Matches strings (letters only)
  • <slug:name> - Matches URL slugs (lowercase letters, numbers, hyphens)
  • <boolean:name> - Matches true/false
  • Parameters are automatically extracted to req.params

​
Test Your Dynamic Routes

Test the new endpoints: 
curl http://localhost:3000/123
# Returns: {"message": "User ID: 123", "id": "123"}

​
Handle Different HTTP Methods

By default, routes accept all HTTP methods. To restrict methods, use the methods option: 
url.addPath("/users", (req, res) => {
  res.sendJson({ message: "User list" }, 200);
}, { methods: ["GET"] });

url.addPath("/users", (req, res) => {
  res.sendJson({ message: "User created" }, 201);
}, { methods: ["POST"] });

​
Organize Routes with Modules

As your application grows, organize routes into modules: 
import { asi, url } from '@asimilation/core';

asi.setup(3000, import.meta.url);

// Create route modules
const apiModule = url.createRouteModule("/api");
const v1Module = apiModule.createRouteModule("/v1");

// Routes are automatically namespaced
v1Module.addPath("/users", (req, res) => {
  res.sendJson({ users: [] }, 200);
}); // Maps to /api/v1/users

v1Module.addPath("/posts", (req, res) => {
  res.sendJson({ posts: [] }, 200);
}); // Maps to /api/v1/posts

asi.run();

​
Complete Example

Here’s a complete example with multiple routes and modules:
server.ts
import { asi, url } from '@asimilation/core';

asi.setup(3000, import.meta.url);

// Root route
url.addPath("/", (req, res) => {
  res.sendJson({ 
    message: "Welcome to Asimilation API",
    version: "1.0.0"
  }, 200);
});

// API module
const api = url.createRouteModule("/api");

// User routes
api.addPath("/users", (req, res) => {
  res.sendJson({ users: [] }, 200);
}, { methods: ["GET"] });

api.addPath("/users/<int:id>", (req, res) => {
  res.sendJson({ 
    user: { id: req.params.id, name: "John Doe" }
  }, 200);
}, { methods: ["GET"] });

// Post routes
api.addPath("/posts", (req, res) => {
  res.sendJson({ posts: [] }, 200);
}, { methods: ["GET"] });

api.addPath("/posts/<slug:slug>", (req, res) => {
  res.sendJson({ 
    post: { slug: req.params.slug, title: "Sample Post" }
  }, 200);
}, { methods: ["GET"] });

asi.run();

console.log("Server running on http://localhost:3000");

​
Next Steps

Routing

Learn more about URL patterns and route configuration

Request & Response

Work with request data and send responses

Middleware

Add authentication, logging, and custom processing

Error Handling

Handle errors gracefully in your application
For a production setup, consider adding environment variables for configuration, proper error handling, and logging middleware.

Build docs developers (and LLMs) love

Get started for freeTalk to us