🗂️ Router Object and Modularization

Why Modularize?

As an app grows, one route file becomes a bottleneck: hard to navigate, prone to merge conflicts, and full of repeated path prefixes. Modularization splits it into logical units that map to how you actually think about the domain.

💡 Analogy: A large Express app is a growing city. Without planning it's a chaotic maze. Modularization is zoning — distinct neighborhoods (routers), each with its own internal organization, connected by clear main roads (mount paths). Newcomers find their way and maintenance stays sane.

The Express Router

An express.Router() is a lightweight, mountable mini-app. It supports the same .get(), .post(), .use(), .route(), and .param() methods as the app object, but you define it in its own file and plug it in later.

// routes/pages.routes.js
const express = require('express');
const router = express.Router();

router.get('/', (req, res) => res.send('Home page'));
router.get('/about', (req, res) => res.send('About page'));

module.exports = router;

// app.js
const express = require('express');
const app = express();
const pages = require('./routes/pages.routes');

app.use('/', pages);            // mount the router
app.listen(3000, () => console.log('http://localhost:3000'));

The pattern is always the same four steps: create a router, define routes on it, export it, mount it.

🌍 Real-world: Platforms with thousands of endpoints (profiles, messaging, jobs, payments) give each domain its own router module. Finding "where does POST /messages live?" becomes obvious instead of a scroll through one giant file.

Mounting & Path Prefixes

When you mount a router at a prefix, that prefix is prepended to every route defined inside it. A router that defines / and /:id, mounted at /api/users, produces /api/users and /api/users/:id.

// routes/user.routes.js
const router = require('express').Router();
router.get('/',    (req, res) => res.json({ message: 'All users' }));
router.get('/:id', (req, res) => res.json({ id: req.params.id }));
module.exports = router;

// app.js — mount several routers side by side
app.use('/api/users',    require('./routes/user.routes'));
app.use('/api/products', require('./routes/product.routes'));
app.use('/auth',         require('./routes/auth.routes'));

💡 Analogy: Mounting is assigning departments to floors. HR (a router) organizes its own offices, but the floor number (mount path) becomes part of every office's full address. Move HR to a new floor and all its addresses update at once.

Router-Level Middleware

A router can carry its own middleware with router.use(). It runs only for routes defined on that router and only for routes declared after it — a clean way to scope logging, auth, or rate limiting to one section of the app.

// routes/protected.routes.js
const router = require('express').Router();

// Applies to every route below, on this router only
router.use((req, res, next) => {
  console.log(`${req.method} ${req.originalUrl}`);
  next();
});

router.use((req, res, next) => {
  if (req.headers['x-api-key'] !== process.env.API_KEY) {
    return res.status(401).json({ error: 'API key required' });
  }
  next();
});

router.get('/',  (req, res) => res.json({ message: 'Protected data' }));
router.post('/', (req, res) => res.json({ message: 'Created' }));

module.exports = router;

Path-scoped middleware and mount-time middleware

You can restrict middleware to a sub-path inside a router, and you can inject middleware at the moment you mount a router:

const adminRouter = require('express').Router();

adminRouter.use('/settings', (req, res, next) => {
  if (!req.user?.permissions.includes('manage_settings')) {
    return res.status(403).json({ error: 'Settings permission required' });
  }
  next();
});

adminRouter.get('/dashboard', (req, res) => res.json({ ok: true }));
adminRouter.get('/settings',  (req, res) => res.json({ settings: {} }));

// authenticate runs before the whole admin router is entered
app.use('/admin', authenticate, adminRouter);

🌍 Real-world: Admin dashboards use router-level middleware so store owners, staff, and developers all reach the dashboard but only see the sections their permissions allow — enforced once per router, not repeated on every route.

Organizing by Resource

The most common structure gives each resource its own router file, wired together by a single routes/index.js that the app mounts under one prefix.

project/
├── app.js
├── routes/
│   ├── index.js          # combines all resource routers
│   ├── user.routes.js
│   ├── product.routes.js
│   └── auth.routes.js
├── controllers/          # handlers (next lesson)
├── models/
└── middleware/

// routes/user.routes.js
const router = require('express').Router();
const userController = require('../controllers/user.controller');
const { authenticate, authorize } = require('../middleware/auth');

router.get('/',    userController.getAllUsers);
router.get('/:id', userController.getUserById);
router.post('/',   authenticate, userController.createUser);
router.put('/:id', authenticate, authorize('admin'), userController.updateUser);
router.delete('/:id', authenticate, authorize('admin'), userController.deleteUser);

module.exports = router;

// routes/index.js — one place to see the whole surface
const router = require('express').Router();
router.use('/users',    require('./user.routes'));
router.use('/products', require('./product.routes'));
router.use('/auth',     require('./auth.routes'));
module.exports = router;

// app.js
app.use('/api', require('./routes'));   // → /api/users, /api/products, ...

💡 Analogy: Resource-based organization is a well-run library. Each section (Fiction, Reference) has its own shelving and rules; the front desk directory (index.js) just points you to the right section, which then manages itself.

Nested Routers & mergeParams

Resources often nest: a user has posts, a post has comments. You express this by mounting one router inside another. The catch: by default a child router cannot see the parent's URL params. Turn on mergeParams: true to fix that.

// routes/post.routes.js  →  mounted at /users/:userId/posts
const router = require('express').Router({ mergeParams: true }); // key!

router.get('/', (req, res) => {
  // req.params.userId is visible thanks to mergeParams
  res.json({ message: `All posts for user ${req.params.userId}` });
});

router.get('/:postId', (req, res) => {
  const { userId, postId } = req.params;
  res.json({ userId, postId });
});

module.exports = router;

// routes/user.routes.js
const router = require('express').Router();
const postRouter = require('./post.routes');

router.get('/:userId', (req, res) => res.json({ id: req.params.userId }));
router.use('/:userId/posts', postRouter);   // nest it

module.exports = router;

Nesting composes to any depth — comments under posts under users:

API Versioning & Factories

Routers make versioning natural: keep v1 and v2 as separate modules and mount them under different prefixes so existing clients keep working while new ones adopt the new shape.

// routes/index.js
const router = require('express').Router();
router.use('/v1/users', require('./v1/user.routes'));
router.use('/v2/users', require('./v2/user.routes'));
module.exports = router;
// → /api/v1/users  and  /api/v2/users

Router factories

When many resources share the same CRUD shape, a factory function generates a consistent router so you write the boilerplate once:

// utils/resourceRouter.js
function createResourceRouter(controller, { authenticate } = {}) {
  const router = require('express').Router({ mergeParams: true });

  router.get('/',    controller.getAll);
  router.get('/:id', controller.getById);

  const guard = authenticate ? [authenticate] : [];
  router.post('/',      ...guard, controller.create);
  router.put('/:id',    ...guard, controller.update);
  router.delete('/:id', ...guard, controller.delete);

  return router;
}
module.exports = createResourceRouter;

// usage
const userRouter = createResourceRouter(userController, { authenticate });
app.use('/api/users', userRouter);

🌍 Real-world: Payment and content platforms maintain several API versions at once via router-based structures, letting integrators upgrade on their own schedule while old versions stay backward-compatible.

Hands-on Exercise

// routes/post.routes.js
const router = require('express').Router({ mergeParams: true });
router.get('/', (req, res) =>
  res.json({ message: `Posts for user ${req.params.userId}` }));
module.exports = router;

// routes/user.routes.js
const router = require('express').Router();
const postRouter = require('./post.routes');
router.get('/',        (req, res) => res.json({ users: [1, 2, 3] }));
router.get('/:userId', (req, res) => res.json({ id: req.params.userId }));
router.use('/:userId/posts', postRouter);
module.exports = router;

// routes/index.js
const router = require('express').Router();
router.use('/users', require('./user.routes'));
module.exports = router;

// app.js
const express = require('express');
const app = express();
app.use('/api', require('./routes'));
app.listen(3000, () => console.log('http://localhost:3000'));
// GET /api/users/5/posts → { "message": "Posts for user 5" }

Best Practices

Summary & Quiz

📚 Further Reading

• Express — Router API
• Express — Router-level middleware
• Supertest — HTTP assertions for isolated router tests

🚀 What's Next?

Your routers still hold their logic inline. Next we'll extract that logic into controllers, so routes describe what the API exposes and controllers own how it works.