{"id":17751,"library":"koa-path-canonicalizer","title":"Koa Path Canonicalizer Middleware","description":"koa-path-canonicalizer is a Koa middleware designed to automatically redirect incoming requests to a canonicalized path. This typically involves normalizing URL structures, such as ensuring consistent trailing slashes or removing duplicate slashes, which helps improve SEO by preventing duplicate content issues and maintaining clean URLs. The package is currently at version 0.2.0, indicating it's still in early development stages, with a relatively stable and slow release cadence, having had only two minor releases since its initial launch. Its key differentiator is its focused and straightforward integration into Koa applications for basic path normalization, offering a minimalist solution without extensive configuration overhead compared to broader routing libraries.","status":"active","version":"0.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/herp-inc/koa-path-canonicalizer","tags":["javascript","typescript"],"install":[{"cmd":"npm install koa-path-canonicalizer","lang":"bash","label":"npm"},{"cmd":"yarn add koa-path-canonicalizer","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-path-canonicalizer","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime peer dependency for any Koa middleware, providing the core application context.","package":"koa","optional":false}],"imports":[{"note":"This package uses named exports. Attempting a default import will result in an undefined function.","wrong":"import pathCanonicalizer from 'koa-path-canonicalizer';","symbol":"pathCanonicalizer","correct":"import { pathCanonicalizer } from 'koa-path-canonicalizer';"},{"note":"The `require` statement returns an object with named exports, so destructuring is necessary to get the `pathCanonicalizer` function directly.","wrong":"const pathCanonicalizer = require('koa-path-canonicalizer');","symbol":"pathCanonicalizer (CommonJS)","correct":"const { pathCanonicalizer } = require('koa-path-canonicalizer');"},{"note":"Import the `Options` type for type-safe configuration of the middleware in TypeScript projects.","symbol":"Options (TypeScript)","correct":"import type { Options } from 'koa-path-canonicalizer';"}],"quickstart":{"code":"import Koa from 'koa';\nimport { pathCanonicalizer } from 'koa-path-canonicalizer';\n\nconst app = new Koa();\n\n// Apply the canonicalizer middleware early in the chain.\n// By default, it removes trailing slashes and normalizes multiple slashes.\napp.use(pathCanonicalizer({\n  trailingSlash: false, // Ensures no trailing slash (e.g., /foo/ -> /foo)\n  normalizeMultiSlashes: true // Ensures //foo/bar -> /foo/bar\n}));\n\n// Example route to demonstrate functionality\napp.use(async (ctx, next) => {\n  if (ctx.path === '/') {\n    ctx.body = 'Welcome to the homepage!';\n  } else if (ctx.path === '/hello') {\n    ctx.body = `Hello from ${ctx.path}! Try navigating to /hello/ or //hello.`;\n  } else {\n    ctx.body = `You are at ${ctx.path}`;\n  }\n  await next();\n});\n\nconst PORT = process.env.PORT ?? 3000;\napp.listen(PORT, () => {\n  console.log(`Koa server running on http://localhost:${PORT}`);\n  console.log('Try visiting:');\n  console.log(`- http://localhost:${PORT}/hello/ (should redirect to /hello)`);\n  console.log(`- http://localhost:${PORT}///hello (should redirect to /hello)`);\n});","lang":"typescript","description":"Demonstrates setting up a basic Koa application with `koa-path-canonicalizer` to automatically redirect requests to their canonicalized paths, showing how to remove trailing slashes and normalize multiple slashes."},"warnings":[{"fix":"Initialize the middleware with `pathCanonicalizer({ trailingSlash: true })` if you want to enforce trailing slashes, or `false` to enforce no trailing slashes.","message":"The default behavior of `koa-path-canonicalizer` for trailing slashes might not align with all application requirements. By default, it removes trailing slashes. If your application expects or requires trailing slashes, you must explicitly configure the `trailingSlash` option.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure your Koa application is configured to trust proxy headers using `app.proxy = true;` and that your proxy correctly sets `X-Forwarded-For`, `X-Forwarded-Host`, and `X-Forwarded-Proto`.","message":"When deployed behind reverse proxies or load balancers, `koa-path-canonicalizer` might generate incorrect redirect URLs if the `X-Forwarded-Proto` or `X-Forwarded-Host` headers are not correctly processed by Koa's `ctx.url` or `ctx.href`. This can lead to redirects pointing to `http` instead of `https`, or an incorrect domain.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Place `koa-path-canonicalizer` early in your middleware chain and thoroughly test interactions with any other middleware that performs redirects or path rewrites. Configure options like `trailingSlash` to prevent conflicts with other components.","message":"Combining `koa-path-canonicalizer` with other path-manipulating middleware (e.g., custom redirect logic, other routing middleware that modifies `ctx.path`) can lead to infinite redirect loops. Ensure only one piece of middleware is responsible for canonicalizing paths.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Ensure `koa-path-canonicalizer` is mounted early in your Koa middleware chain, typically before any middleware that might send a response or perform its own redirects based on the original path.","cause":"Another middleware or route handler has already sent a response (e.g., `ctx.body = '...'`, `ctx.redirect()`) before `koa-path-canonicalizer` attempts to issue a redirect, leading to a conflict.","error":"Error: Can't set headers after they are sent."},{"fix":"Change your import statement from `import pathCanonicalizer from 'koa-path-canonicalizer';` to `import { pathCanonicalizer } from 'koa-path-canonicalizer';`.","cause":"This error typically occurs in ESM contexts (e.g., TypeScript or modern Node.js) when attempting to use a default import for `koa-path-canonicalizer`, but the package only provides named exports.","error":"TypeError: (0 , _koaPathCanonicalizer.pathCanonicalizer) is not a function"},{"fix":"Review all components in your request path (nginx, Apache, other Koa middleware) that might modify the URL. Configure `koa-path-canonicalizer`'s `trailingSlash` option explicitly (`true` or `false`) to match the desired canonical form and avoid conflicts.","cause":"The browser or client reports too many redirects, indicating an infinite loop. This often happens when `koa-path-canonicalizer`'s redirection logic conflicts with another server configuration (e.g., a reverse proxy, web server rewrite rules) or another Koa middleware that also manipulates paths or performs redirects.","error":"ERR_TOO_MANY_REDIRECTS"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}