Koa Stylus Middleware

0.1.0 verified Thu Apr 23 auth: no javascript abandoned

koa-stylus provides middleware to integrate the Stylus CSS preprocessor with Koa.js web applications. This package is extremely old and was last published over a decade ago (version 0.1.1, 11 years ago). It is designed exclusively for Koa v1.x, which utilized generator functions for middleware. Modern Koa versions (v2.x and v3.x, which use `async/await`) are incompatible with this middleware without significant modifications or a compatibility layer. The package is effectively abandoned, has no ongoing development or release cadence, and lacks support for contemporary Node.js or Koa features. Its primary differentiator was its simple integration with the then-current Koa API for Stylus compilation on the fly.

Common errors

error TypeError: app.use() requires a generator function ↓

cause `koa-stylus` is a Koa v1.x middleware which uses generator functions, while Koa v2.x and newer expect async functions.

fix

This error indicates an incompatibility with modern Koa versions. You can try to use koa-convert as app.use(require('koa-convert')(stylus('./public')));, but full compatibility is not guaranteed, and migrating away from this middleware is recommended.

error Cannot find module 'stylus' ↓

cause The 'stylus' package, a dependency of 'koa-stylus', was not installed or was temporarily unavailable in the npm registry (as happened in the past due to a security incident).

fix

Ensure 'stylus' is correctly listed in your package.json and run npm install. If issues persist, check the official stylus npm page for any current availability problems or security advisories.

Warnings

breaking This package is built for Koa v1.x, which uses generator functions for middleware. Koa v2.x and later transitioned to `async/await` functions, making `koa-stylus` fundamentally incompatible with modern Koa versions without a `koa-convert`-like shim or extensive refactoring. ↓

fix For modern Koa (v2+), consider manually compiling Stylus or using a build pipeline. If `koa-stylus` functionality is critical, you would need to wrap it with `koa-convert` (e.g., `app.use(convert(stylus('./public')))`) and potentially deal with other incompatibilities.

gotcha The `koa-stylus` package is over a decade old and has been abandoned. It has not received updates for compatibility with newer Node.js versions, security patches, or feature enhancements. Using unmaintained software can expose applications to security vulnerabilities or unexpected behavior with newer environments. ↓

fix It is strongly recommended to avoid this package. Instead, preprocess Stylus into CSS during your build step (e.g., using Gulp, Webpack, or a simple npm script) and serve the resulting static CSS files directly.

gotcha The underlying `stylus` package itself (the CSS preprocessor) has experienced supply chain issues, including being temporarily removed from the npm registry due to a maintainer's account compromise. While these issues were resolved for `stylus`, the general lack of maintenance of `koa-stylus` increases the risk of unpatched vulnerabilities or dependency conflicts. ↓

fix Always audit your dependencies. For `stylus` specifically, ensure you are using a recent, uncompromised version if you decide to use it. For `koa-stylus`, the risk is compounded by its abandonment.

Install

npm install koa-stylus

yarn add koa-stylus

pnpm add koa-stylus

Imports

stylus
wrong
```
import stylus from 'koa-stylus';
```
correct
```
const stylus = require('koa-stylus');
```
This package is CJS-only. Koa 1.x and older Node.js versions relied on CommonJS `require()`.
Koa
wrong
```
import Koa from 'koa';
```
correct
```
const Koa = require('koa');
```
The example uses `require('koa')`, consistent with Koa 1.x. Modern Koa (v2+) uses `import Koa from 'koa'` for ESM.

Quickstart

This example demonstrates how to set up `koa-stylus` with Koa v1.x to automatically compile Stylus files and serve them alongside other static assets.

const Koa = require('koa');
const stylus = require('koa-stylus');
const serve = require('koa-static');
const app = new Koa();

// Configure Stylus middleware to compile .styl files in the './public' directory
app.use(stylus('./public'));

// Serve static files from the './public' directory
app.use(serve('./public'));

// Listen on port 3000
app.listen(3000, () => {
  console.log('Koa Stylus server listening on http://localhost:3000');
  console.log('Ensure you have a `public` directory with .styl files and other static assets.');
});