polka

library2.5.0jsnpmunverified

Polka is a minimalist, high-performance web server framework for Node.js, designed to be fast and provide an Express.js-like API with a significantly smaller footprint. While the current stable version is 0.5.2, active development is happening on the `1.0.0-next` series, which frequently releases patch and minor versions, indicating a rapid release cadence for the upcoming major version. Key differentiators include its small core, focus on raw speed, and modular design through companion packages like `@polka/compression`. It provides essential routing and middleware capabilities, making it suitable for building lightweight APIs and web services where performance is critical. The `1.0.0-next` series also introduces explicit support for ESM, TypeScript (`node16`/`nodenext`), and even Deno runtimes, broadening its applicability beyond traditional Node.js CommonJS environments.

web-framework http-networking

npm install polka

github ↗package ↗

INSTALL

IMPORT

SIG · POLKA

polka

web-frameworkjavascriptv2.5.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

polka

✓ import { polka } from 'polka';

✗ const polka = require('polka');

While `require('polka')` works for older versions or CommonJS environments, `polka`'s `1.0.0-next` series is optimized for ESM. Use `import` for best compatibility with TypeScript and modern Node.js features, including type declarations.

Request, Response

✓ import type { Request, Response } from 'polka';

These types are available for use in TypeScript projects to correctly type middleware and route handlers, especially since `polka@1.0.0-next.24` introduced improved TypeScript support.

compression

✓ import compression from '@polka/compression';

✗ import { compression } from 'polka';

The `compression` middleware is provided by the separate `@polka/compression` package, added in `polka@1.0.0-next.25`. It is not a named export from `polka` itself and must be imported from its own package.

Demonstrates setting up a basic Polka server, defining a root route and a parameterized route, and starting the server to listen for requests on port 3000.

import { polka } from 'polka'; import type { Request, Response } from 'polka'; const app = polka(); app.get('/', (req: Request, res: Response) => { res.setHeader('Content-Type', 'text/plain'); res.end('Hello from Polka!'); }); app.get('/user/:id', (req: Request, res: Response) => { res.setHeader('Content-Type', 'application/json'); res.end(JSON.stringify({ userId: req.params.id, message: 'User data' })); }); app.listen(3000, (err: Error) => { if (err) throw err; console.log('> Running on http://localhost:3000'); });

Debug

Known issues

breakingIn `polka@1.0.0-next.21` and newer, error objects passed to `next()` must use the `status` property for HTTP status codes instead of `code`. The `code` property (e.g., 'ENOENT') is no longer supported for setting HTTP status and can lead to invalid status codes if used. Ensure all custom error objects use `status`.

fix

Change `error.code = 404` to `error.status = 404` in your error handling middleware.

affects: >=1.0.0-next.21

breakingStarting from `polka@1.0.0-next.16`, `req.url` and `req.path` values are no longer automatically `decodeURIComponent`-ed. These properties will remain percent-encoded, aligning with Express's default behavior. `req.params` values, however, are still automatically decoded. This may affect middleware expecting decoded paths.

fix

Manually `decodeURIComponent(req.url)` or `decodeURIComponent(req.path)` if your application logic or middleware relies on decoded values from these properties.

affects: >=1.0.0-next.16

gotchaWith `polka@1.0.0-next.28`, CommonJS modules (accessed via `require`) no longer include the `node:` prefix for built-in modules, while ESM modules (accessed via `import`) *still* use the `node:` prefix. This distinction is critical for hybrid packages and environments supporting native ESM, particularly when targeting Node.js 14.18+ or 16+.

fix

Ensure your Node.js version is 14.18+ or 16+ for `node:` prefix support. Be mindful of module type (CommonJS vs. ESM) when importing built-in modules within Polka applications to avoid 'module not found' errors.

affects: >=1.0.0-next.28

breakingIn `@polka/url@1.0.0-next.20`, the `toDecode` parameter was removed from the `parse` function. If you were explicitly using this parameter to control URL decoding, your code will break.

fix

Remove the `toDecode` parameter from calls to `parse` in `@polka/url`. The default behavior for `req.url`/`req.path` is now percent-encoded.

affects: >=1.0.0-next.20

gotchaFor TypeScript users, `polka@1.0.0-next.24` and above provide improved support for `node16`, `nodenext`, and `bundler` module resolutions. Ensure your `tsconfig.json` is configured correctly for optimal type inference and module resolution, especially in hybrid ESM/CJS projects.

fix

Review your `tsconfig.json` `moduleResolution` and `module` options. Consider `nodenext` or `bundler` for modern Node.js and bundler environments to leverage Polka's type declarations fully.

affects: >=1.0.0-next.24

Errors

Common errors & fixes

Cannot find module 'node:path'

Attempting to import a Node.js built-in module with a `node:` prefix in a CommonJS context or an older Node.js environment that doesn't support the prefix for CJS modules.

fix

If using `require()`, ensure you are on `polka@1.0.0-next.28` or newer and that `node:` prefixes are not used in CommonJS modules. If using `import`, ensure your Node.js version is 14.18+ or 16+ and that `node:` prefixes are included.

TypeError: Cannot set headers after they are sent to the client

Attempting to modify response headers or send data after `res.end()` or `next()` has already been called and the response stream is closed or being sent.

fix

Ensure that `res.end()` or `next()` is called only once per request and that no further modifications to `res` occur afterwards. Use `return next(err)` or `return res.end()` to prevent further execution in middleware or route handlers.

Error: Route not found for GET /something

No matching route defined for the requested path and HTTP method.

fix

Verify that a `polka.get('/something', ...)` or `polka.use('/something', ...)` route is correctly defined to handle the specific incoming request path and HTTP method. Ensure middleware is correctly chained or `next()` is called to pass control.

Upgrade

Version history

2.5.0latest on npm

Audit

Dependencies

@polka/compressionoptionalOptional middleware for adding HTTP compression (gzip, brotli).

@polka/bodyoptionalCommonly used for parsing request bodies (e.g., JSON, form data).

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/lukeed/polka ↗

packagehttps://www.npmjs.com/package/polka ↗