miniframe-router
Version:
Simple router for Express.js, making routes and controllers easy to manage.
252 lines (185 loc) • 5.14 kB
Markdown
# `MiniframeJS/Router`
A simple yet powerful routing solution for `Express.js` applications that provides a clean and intuitive way to organize routes and controllers.
## Features
- Simple route definition syntax
- Controller-based actions
- Scoped routes for better organization
- Automatic controller loading
## Documentation
- Development: [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)
- Development (RU): [docs/DEVELOPMENT.ru.md](docs/DEVELOPMENT.ru.md)
- Demo app Skeleton: [docs/demo/README.md](docs/demo/README.md)
## Installation
```bash
npm install miniframe-router
```
```bash
yarn add miniframe-router
```
```bash
pnpm add miniframe-router
```
## Usage
### Basic Routes
`routes/index.ts`
```ts
import { root, get, post, getRouter } from "miniframe-router";
// Define root route
root("index#index");
// Define GET and POST routes
get("/users", "users#show");
post("/users", "users#update");
// Define GET and POST routes
get("/posts", "posts#show");
post("/posts", "posts#update");
export default getRouter;
```
### Routes with Middleware
You can add middleware to any route:
```ts
import { get, post, routeScope as scope } from "miniframe-router";
import { authenticate } from "./middlewares/auth";
import { validateUser } from "./middlewares/validation";
// Single middleware
get("/users/:id", "users#show", {
withMiddlewares: [authenticate],
});
// Multiple middleware in execution order
post("/users", "users#create", {
withMiddlewares: [authenticate, validateUser],
});
// Middleware with scoped routes
scope("admin", () => {
get("/users", "users#show", {
withMiddlewares: [authenticate],
});
post("/users", "users#create", {
withMiddlewares: [authenticate, validateUser],
});
});
```
### Scoped Routes with Middleware
You can add middleware to both individual routes and entire scopes:
```ts
import { authenticate } from "./middlewares/auth";
import { validateUser } from "./middlewares/validation";
import { logRequest } from "./middlewares/logging";
// Apply middleware to all routes within scope
scope(
"admin",
() => {
// These routes will require authentication
get("/users", "users#index");
post("/users", "users#create");
// This route will require both authentication and validation
post("/users/:id", "users#update", {
withMiddlewares: [validateUser],
});
},
{
withMiddlewares: [authenticate],
}
);
// Combine multiple middleware for scope
scope(
"api",
() => {
get("/stats", "stats#index");
get("/health", "health#check");
},
{
withMiddlewares: [authenticate, logRequest],
}
);
```
Middleware specified in the scope options will be applied to all routes within that scope.
You can still add route-specific middleware that will be executed after the scope middleware.
Application files structure:
```bash
src
index.ts
routes/
index.ts
controllers/
indexController.ts
usersController.ts
postsController.ts
```
`index.ts`
```ts
import cors from "cors";
import cookieParser from "cookie-parser";
import getRoutes from "./routes";
const app = express();
app.use(
cors({
origin: ["http://localhost:3000"],
credentials: true,
})
);
app.use(cookieParser());
app.use(express.json());
app.use(getRoutes()); // <<< USE ROUTES
app.listen(4000, () => {
console.log(`Server is running on port: 4000`);
});
```
### Scoped Routes
Group related routes under a common prefix:
`routes/index.ts`
```ts
import {
root,
get,
post,
getRouter,
routeScope as scope,
} from "miniframe-router";
scope("admin", () => {
get("/users", "users#show");
post("/users", "users#update");
get("/posts", "posts#show");
post("/posts", "posts#update");
});
export default getRouter;
```
This will create routes:
- GET `/admin/users` -> `controllers/admin/usersController.ts` (`show` action)
- POST `/admin/users` -> `controllers/admin/usersController.ts` (`update` action)
- GET `/admin/posts` -> `controllers/admin/postsController.ts` (`show` action)
- POST `/admin/posts` -> `controllers/admin/postsController.ts` (`update` action)
### Controllers Structure
Controllers should be placed in the `controllers` directory. For scoped routes, controllers are automatically looked up in the corresponding subdirectory.
```bash
src
index.ts
routes/
index.ts
controllers/
indexController.ts
usersController.ts
postsController.ts
admin/
usersController.ts
postsController.ts
```
Example controller:
`controllers/usersController.ts`
```typescript
import { Request, Response } from "express";
export const show = (req: Request, res: Response) => {
res.send("Users list");
};
export const update = (req: Request, res: Response) => {
res.send("User updated");
};
```
## API Reference
- `root(controllerAction)`: Define root route (/)
- `get(path, controllerAction)`: Define GET route
- `post(path, controllerAction)`: Define POST route
- `routeScope(prefix, callback)`: Group routes under a common prefix
### License
MIT.
### Author
Ilya N. Zykin | [the-teacher](https://github.com/the-teacher)