The Revolutionary
Node.js Framework

Production API in Minutes

Create a folder inside modules/ with a module.js file — SpaceNode automatically discovers your routes, controllers, services, and DTOs. No manual wiring. Define your endpoints as arrays: method, path, handler, and optional guards. Controllers receive the request context as the first argument and auto-injected services as the second. Guards like auth, admin, and dto:product run before the handler — no middleware chains, no next() calls.

Project Structure

my-api/
├── index.js                        // entry point — createApp + global config
├── package.json
└── modules/                        // each folder = one module (auto-discovered)
    ├── auth/
    │   ├── module.js               // prefix: '/auth', routes: [...]
    │   ├── auth.controller.js      // register, login, logout handlers
    │   └── auth.service.js         // hashing, tokens, sessions
    ├── product/
    │   ├── module.js               // prefix: '/products', routes: [...]
    │   ├── product.controller.js   // list, getById, create, update, remove
    │   ├── product.service.js      // DB queries, business logic
    │   └── product.dto.js          // validation schemas for create/update
    ├── category/
    │   ├── module.js
    │   ├── category.controller.js
    │   └── category.service.js
    └── cart/
        ├── module.js
        ├── cart.controller.js
        └── cart.service.js

index.js — Entry Point

import { createApp, defineAuth, defineGuard } from 'spacenode'

// defineAuth — tell SpaceNode how to resolve a user from a token
defineAuth(async (token) => {
  const session = await Token.findOne({ token })
  if (!session) return null
  return User.findById(session.userId) // → request.user
})

// defineGuard — custom guards reusable across all modules
defineGuard('admin', () => (request) => {
  if (!request.user) request.error(401, 'Authorization required')
  if (request.user.role !== 'admin') request.error(403, 'Admin only')
})

// createApp — discovers all modules/ automatically
const app = await createApp({
  openapi: true,    // auto-generate OpenAPI 3.0 docs at /api-docs
  watch:   true,    // auto-restart on file changes (dev mode)
  debug:   true,    // verbose logging
})

app.listen(3000)

module.js — Route Declaration

// modules/product/module.js
// Each module exports: prefix, optional pipe, and routes array
// Routes: [METHOD, PATH, HANDLER_NAME, [GUARDS]]
export default {
  prefix: '/products',
  pipe: ['cors', 'logger'],          // run on every route in this module
  routes: [
    ['GET',    '',      'list'],                                 // GET /products
    ['GET',    '/:id',  'getById'],                              // GET /products/:id
    ['POST',   '',      'create',  ['auth', 'dto:product']], // auth + validation
    ['PUT',    '/:id',  'update',  ['auth', 'admin']],      // admin only
    ['DELETE', '/:id',  'remove',  ['auth', 'admin']],      // admin only
  ],
}
// 'list' → calls list() from product.controller.js
// 'auth' → built-in guard (uses defineAuth callback)
// 'admin' → custom guard (defined in index.js)
// 'dto:product' → validates body against product.dto.js

Controller — Request Handlers

// modules/product/product.controller.js
// 1st arg — request context (destructure what you need)
// 2nd arg — DI services (auto-injected from *.service.js)

export async function list({ query, send }, { productService }) {
  const { page = 1, limit = 20, search } = query
  const result = await productService.list({ page, limit, search })
  send(result) // → { items: [...], total: 42, pages: 3 }
}

export async function create({ body, send }, { productService }) {
  const product = await productService.create(body)
  send(201, product) // status 201 + JSON body
}

export async function remove({ params, send }, { productService }) {
  await productService.remove(params.id)
  send({ deleted: true })
}
// productService is auto-injected from product.service.js
// Services from OTHER modules also available (e.g. categoryService)

• Auto-discovery — drop a folder into modules/, everything is wired automatically
• DI container — services from all modules available as the 2nd handler argument
• Guards — auth, roles, rate-limit, CORS, logging — just reference by name
• DTO validation — array-based or plug in Zod/Joi/Yup
• OpenAPI 3.0 — auto-generated from your routes and DTOs
• Event bus — inter-module communication without imports

// index.js — enable SSR with one option
const app = await createApp({
  views:  './views',   // enables built-in template engine
  static: './public',  // serves CSS, images, JS
})

// simple page — one line
app.render('GET', '/', 'pages/home', { title: 'Welcome' })

// controller with auth, DI, and template rendering
export async function profile(req, { userService }) {
  const user = await userService.getById(req.user.id)
  await req.render('pages/profile', { user })
}

// views/pages/home.html — template syntax
// [# layout 'layouts/main' ]
// <h1>[= title ]</h1>
// [# each posts as post ]
//   <article>[= post.title ]</article>
// [/each]
// [# include 'partials/footer' ]

// index.js — serve your frontend app
import { createApp } from 'spacenode'

const app = await createApp({
  static: './public',  // serve files from ./public
  // spa: true         ← default — all routes fallback to index.html
  // spa: false         ← for multi-page static sites
})

// add API routes alongside your static files
app.setRoute('GET', '/api/status', ({ send }) => {
  send({ status: 'ok', uptime: process.uptime() })
})

app.listen(3000)
// public/index.html  → served at /
// public/style.css   → served at /style.css
// public/app.js      → served at /app.js
// /about, /dashboard  → SPA fallback to index.html