# owebjs

> A flexible and modern web framework built on top of Fastify

Latest version **1.4.8** (published 2026-02-07) · MIT license · 0 weekly downloads

## Install

```sh
npm install owebjs
pnpm add owebjs
yarn add owebjs
bun add owebjs
```

## Health

**Score 50/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: insecure dependencies.

## Facts

| | |
|---|---|
| Version | 1.4.8 |
| Published | 2026-02-07 |
| First published | 2023-09-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 11 |
| Unpacked size | 51.4 KB |
| Known vulnerabilities | 0 (+4 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 17 |
| Author | owebjs |
| Maintainers | spongebed, hanzydev |

## Links

- npm: https://www.npmjs.com/package/owebjs
- Repository: https://github.com/owebjs/oweb
- Issues: https://github.com/owebjs/oweb/issues
- npm.io page: https://npm.io/package/owebjs

## Dependencies (11)

- [chalk](https://npm.io/package/chalk.md) ^5.4.1
- [fastify](https://npm.io/package/fastify.md) 4.23.2
- [@babel/core](https://npm.io/package/@babel/core.md) ^7.28.0
- [@babel/types](https://npm.io/package/@babel/types.md) ^7.28.2
- [@babel/parser](https://npm.io/package/@babel/parser.md) ^7.28.0
- [path-to-regexp](https://npm.io/package/path-to-regexp.md) ^8.2.0
- [uWebSockets.js](https://npm.io/package/uWebSockets.js.md) github:uNetworking/uWebSockets.js#v20.52.0
- [@babel/traverse](https://npm.io/package/@babel/traverse.md) ^7.28.0
- [@babel/generator](https://npm.io/package/@babel/generator.md) ^7.28.0
- [@fastify/websocket](https://npm.io/package/@fastify/websocket.md) ^11.2.0
- [@babel/preset-typescript](https://npm.io/package/@babel/preset-typescript.md) ^7.27.1

## Recent versions

- 1.4.8 (latest) — 2026-02-07
- 1.7.0-dev (dev) — 2026-05-27
- 1.6.9-dev — 2026-05-27
- 1.6.8-dev — 2026-05-27
- 1.6.7-dev — 2026-05-27
- 1.6.6-dev — 2026-05-27
- 1.6.5-dev — 2026-05-27
- 1.6.4-dev — 2026-05-27
- 1.6.3-dev — 2026-04-29
- 1.6.1-dev — 2026-03-06
- 1.6.0-dev — 2026-03-06
- 1.5.9-dev — 2026-03-06
- 1.5.8-dev — 2026-03-06
- 1.5.7-dev — 2026-03-06
- 1.5.5-dev — 2026-02-17
- … 42 more at https://npm.io/package/owebjs/versions

## README

# Oweb

A flexible and modern web framework built on top of Fastify, designed for creating scalable and maintainable web applications with file-based routing and hot module replacement.

<p align="center">
  <img src="https://img.shields.io/npm/v/owebjs" alt="npm version">
  <img src="https://img.shields.io/npm/l/owebjs" alt="license">
  <img src="https://img.shields.io/npm/dt/owebjs" alt="downloads">
</p>

## Features

- **File-based Routing**: Automatically generate routes based on your file structure
- **Hot Module Replacement (HMR)**: Update your routes without restarting the server
- **Middleware Support**: Use hooks to add middleware functionality
- **Error Handling**: Global and route-specific error handling
- **TypeScript Support**: Built with TypeScript for better developer experience
- **Plugin System**: Extend functionality with plugins
- **uWebSockets.js Support**: Optional high-performance WebSocket server

## Installation

```bash
npm install owebjs
```

## Quick Start

```javascript
import Oweb from 'owebjs';

// Create and setup the app
const app = await new Oweb().setup();

// Load routes from a directory
await app.loadRoutes({
    directory: 'routes',
    hmr: {
        enabled: true, // Enable hot module replacement
    },
});

// Start the server
await app.start({ port: 3000 });
console.log('Server running at http://localhost:3000');
```

## Creating Routes

Routes are automatically generated based on your file structure. Create a file in your routes directory:

```javascript
// routes/hello.js
import { Route } from 'owebjs';

export default class extends Route {
    async handle(req, res) {
        res.send({ message: 'Hello, World!' });
    }
}
```

This will create a GET route at `/hello`.

### Dynamic Routes

Use brackets to create dynamic route parameters:

```javascript
// routes/users/[id].js
import { Route } from 'owebjs';

export default class extends Route {
    async handle(req, res) {
        res.send({ userId: req.params.id });
    }
}
```

This will create a GET route at `/users/:id`.

### Parameter Validation with Matchers

Use matchers to validate dynamic route parameters:

```javascript
// routes/users/[id=integer].js
import { Route } from 'owebjs';

export default class extends Route {
    async handle(req, res) {
        res.send({ userId: req.params.id });
    }
}
```

```javascript
// matchers/integer.js
export default function (val) {
    return !isNaN(val);
}
```

Then configure Oweb to use your matchers directory:

```javascript
await app.loadRoutes({
    directory: 'routes',
    matchersDirectory: 'matchers', // Directory containing custom matchers
    hmr: {
        enabled: true,
        matchersDirectory: 'matchers', // Optional: Enable HMR for matchers
    },
});
```

Now you can use your custom matchers in route filenames with the syntax `[paramName=matcherName]`.

### HTTP Methods

Specify the HTTP method in the filename:

```javascript
// routes/api/users.post.js
import { Route } from 'owebjs';

export default class extends Route {
    async handle(req, res) {
        // Create a new user
        const user = req.body;
        res.status(201).send({ id: 1, ...user });
    }
}
```

## Middleware (Hooks)

Create hooks to add middleware functionality:

```javascript
// routes/_hooks.js
import { Hook } from 'owebjs';

export default class extends Hook {
    handle(req, res, done) {
        console.log(`${req.method} ${req.url}`);
        done(); // Continue to the next hook or route handler
    }
}
```

Hooks are applied to all routes in the current directory and its subdirectories.

## Error Handling

### Global Error Handler

```javascript
app.setInternalErrorHandler((req, res, error) => {
    console.error(error);
    res.status(500).send({
        error: 'Internal Server Error',
        message: error.message,
    });
});
```

### Route-specific Error Handler

```javascript
import { Route } from 'owebjs';

export default class extends Route {
    async handle(req, res) {
        throw new Error('Something went wrong');
    }

    handleError(req, res, error) {
        res.status(500).send({
            error: 'Route Error',
            message: error.message,
        });
    }
}
```

## Plugins

Oweb supports Fastify plugins and comes with some built-in plugins:

### Using Fastify Plugins

```javascript
import Oweb from 'owebjs';
import fastifyMultipart from '@fastify/multipart';

const app = await new Oweb().setup();

// Register Fastify plugin
await app.register(fastifyMultipart, {
    limits: {
        fileSize: 10 * 1024 * 1024, // 10MB
    },
});
```

### Using Built-in Plugins

```javascript
import { Route } from 'owebjs';
import { ChunkUpload } from 'owebjs/dist/plugins';

export default class extends Route {
    async handle(req, res) {
        const file = await req.file();
        const buffer = await file.toBuffer();

        await ChunkUpload(
            {
                buffer,
                fileName: file.filename,
                currentChunk: +req.query.currentChunk,
                totalChunks: +req.query.totalChunks,
            },
            {
                path: './uploads',
                maxChunkSize: 5 * 1024 * 1024, // 5MB
            },
        );

        return res.status(204).send();
    }
}
```

## Advanced Configuration

### uWebSockets.js Support

```javascript
const app = await new Oweb({ uWebSocketsEnabled: true }).setup();
```

### Custom Route Options

```javascript
import { Route } from 'owebjs';

export default class extends Route {
    constructor() {
        super({
            schema: {
                body: {
                    type: 'object',
                    required: ['username', 'password'],
                    properties: {
                        username: { type: 'string' },
                        password: { type: 'string' },
                    },
                },
            },
        });
    }

    async handle(req, res) {
        // Body is validated according to the schema
        res.send({ success: true });
    }
}
```

---
_Source: https://npm.io/package/owebjs · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._