Usage

Commands

Options

HTTPS Support

Instaserve supports HTTPS with self-signed certificates. To enable HTTPS:

1. Generate certificates:

   ./generate-certs.sh

   This creates cert.pem and key.pem files and adds them to your system's trust store.

2. Run with HTTPS:

   npx instaserve -secure

The certificate generation script:

• Creates a self-signed certificate valid for 365 days
• Automatically adds the certificate to your system trust store (macOS/Linux)
• Prevents browser security warnings

Routes

The routes file (routes.js by default) defines your API endpoints. Each route is a function that handles requests to a specific URL path.

Generating a Routes File

To create a sample routes.js file with example routes and middleware:

npx instaserve generate-routes

This creates a routes.js file in the current directory with example code. If the file already exists, the command will fail to prevent overwriting.

Routes File Validation

Instaserve validates routes files on startup:

• If -api is specified and the file doesn't exist, the server will fail to start
• The routes file must export a default object
• All route handlers must be functions
• Invalid routes files will cause the server to exit with an error message

Basic Route Example

export default {
    // Handle GET /hello
    hello: (req, res, data) => {
        return { message: 'Hello World' }
    }
}

Method-Specific Routes

Routes can be defined with HTTP method prefixes to handle different methods on the same path. Supported methods: GET, POST, PUT, DELETE.

export default {
    // Method-specific routes
    'POST /users': (req, res, data) => {
        return { message: 'Create user', data }
    },
    
    'GET /users': (req, res, data) => {
        return { message: 'Get users' }
    },
    
    'PUT /users': (req, res, data) => {
        return { message: 'Update user', data }
    },
    
    'DELETE /users': (req, res, data) => {
        return { message: 'Delete user', data }
    },
    
    // Path-only routes still work (backward compatible)
    // These match any HTTP method
    hello: (req, res, data) => {
        return { message: 'Hello World' }
    }
}

Method-specific routes take precedence over path-only routes. If no method-specific route matches, the server falls back to path-only route matching.

Special Routes (Middleware)

Routes starting with _ are middleware functions that run on every request before the main route handler. They are useful for:

• Logging requests
• Authentication
• Request modification
• Response headers

Middleware functions can:

• Return false to continue to the next middleware or main route
• Return a truthy value to stop processing and use that as the response
• Modify the request or response objects

Middleware Example

export default {
    // Log every request
    _log: (req, res, data) => {
        console.log(`${req.method} ${req.url}`)
        return false // Continue processing
    },

    // Block unauthorized requests
    _auth: (req, res, data) => {
        if (!data.token) {
            res.writeHead(401)
            return 'Unauthorized'
        }
        return false // Continue if authorized
    }
}

Route Parameters

Each route function receives:

• req - The HTTP request object
• res - The HTTP response object
• data - Combined data from:
  • POST body (if JSON)
  • URL query parameters
  • Form data

Returning Status Codes

Routes can return a 3-digit number (100-999) to set the HTTP status code with an empty response body:

export default {
    'GET /notfound': () => 404,
    'GET /unauthorized': () => 401,
    'GET /forbidden': () => 403,
    'GET /teapot': () => 418, // I'm a teapot
    'GET /created': () => 201
}

Routes can also return:

• Strings - Sent as plain text response
• Objects - Automatically serialized as JSON
• Status codes - 3-digit numbers (100-999) set HTTP status with empty body

Example Routes File

// routes.js
export default {
    // Middleware example
    _debug: (req, res, data) => {
        console.log('Request:', req.url)
        return false // Continue to next route
    },

    // Method-specific routes
    'POST /api/users': (req, res, data) => {
        return { status: 'created', data }
    },
    
    'GET /api/users': (req, res, data) => {
        return { status: 'ok', users: [] }
    },
    
    'GET /api/notfound': () => 404,
    'GET /api/unauthorized': () => 401,

    // Path-only route (matches any method)
    api: (req, res, data) => {
        return { status: 'ok', data }
    },

    // Error handling
    testerror: () => {
        throw new Error('Test error')
    }
}