{"id":18561303,"url":"https://github.com/apostrophecms/redirect","last_synced_at":"2025-10-15T12:32:32.073Z","repository":{"id":45305850,"uuid":"378941295","full_name":"apostrophecms/redirect","owner":"apostrophecms","description":"Manage site redirects for ApostropheCMS.","archived":false,"fork":false,"pushed_at":"2024-10-03T14:14:12.000Z","size":68,"stargazers_count":3,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-03T05:30:04.398Z","etag":null,"topics":["hacktoberfest"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/apostrophecms.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-06-21T13:32:48.000Z","updated_at":"2024-10-03T14:14:01.000Z","dependencies_parsed_at":"2023-02-17T06:46:02.098Z","dependency_job_id":"8179e734-496e-494d-814c-79be4c84c3cb","html_url":"https://github.com/apostrophecms/redirect","commit_stats":{"total_commits":26,"total_committers":8,"mean_commits":3.25,"dds":0.6153846153846154,"last_synced_commit":"847b013142b16ee89c539417c147687b8cbf96f5"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apostrophecms%2Fredirect","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apostrophecms%2Fredirect/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apostrophecms%2Fredirect/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apostrophecms%2Fredirect/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apostrophecms","download_url":"https://codeload.github.com/apostrophecms/redirect/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248150681,"owners_count":21055966,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest"],"created_at":"2024-11-06T22:06:27.869Z","updated_at":"2025-10-15T12:32:27.031Z","avatar_url":"https://github.com/apostrophecms.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/apostrophecms/apostrophe/main/logo.svg\" alt=\"ApostropheCMS logo\" width=\"80\" height=\"80\"\u003e\n\n  \u003ch1\u003eManage site redirects for ApostropheCMS\u003c/h1\u003e\n  \u003cp\u003e\n    \u003ca aria-label=\"Apostrophe logo\" href=\"https://docs.apostrophecms.org\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/MADE%20FOR%20ApostropheCMS-000000.svg?style=for-the-badge\u0026logo=Apostrophe\u0026labelColor=6516dd\"\u003e\n    \u003c/a\u003e\n    \u003ca aria-label=\"Join the community on Discord\" href=\"http://chat.apostrophecms.org\"\u003e\n      \u003cimg alt=\"\" src=\"https://img.shields.io/discord/517772094482677790?color=5865f2\u0026label=Join%20the%20Discord\u0026logo=discord\u0026logoColor=fff\u0026labelColor=000\u0026style=for-the-badge\u0026logoWidth=20\"\u003e\n    \u003c/a\u003e\n    \u003ca aria-label=\"License\" href=\"https://github.com/apostrophecms/blog/blob/main/LICENSE.md\"\u003e\n      \u003cimg alt=\"\" src=\"https://img.shields.io/static/v1?style=for-the-badge\u0026labelColor=000000\u0026label=License\u0026message=MIT\u0026color=3DA639\"\u003e\n    \u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n## Installation\n\nFirst make sure you have an [Apostrophe project](https://apostrophecms.com)!\n\nThen:\n\n```javascript\nnpm install @apostrophecms/redirect\n```\n\n## Configuration\n\nIn `app.js`, add the module to your configuration:\n\n  ```js\n  require('apostrophe')({\n    shortName: 'MYPROJECT',\n    modules: {\n      '@apostrophecms/redirect': {}\n    }\n  });\n  ```\n### `statusCode`\n*Defaults to `302`*\nBy passing `statusCode` to your configuration you can change the default status code value.\nAccepted values are `301` and `302`\n\n```javascript\n// Other modules, then...\n'@apostrophecms/redirect': {\n  options: {\n    statusCode: 301\n  }\n}\n```\n\u003e Note that permanent redirects are cached by Google for a long time. It is a good idea to encourage users to test with a temporary redirect first, then switch to permanent which is an SEO best practice — as long as it's correct.\n\n### `withType`\n*Defaults to `@apostrophecms/page`*\nBy passing `withType` to your configuration you can specify the document type your internal redirects can redirect to.\n\n```javascript\n// Other modules, then...\n'@apostrophecms/redirect': {\n  options: {\n    withType: 'article'\n  }\n}\n```\n\n**Note:** Apostrophe 2 supported creating relationships to multiple doc types from a single interface. This feature doesn't yet exist in the newer versions of Apostrophe, as such redirects can only specify a single doc type to redirect to.\n\n### `skip`\n\nFor performance the redirect check can be skipped for URLs matching certain regular expressions.\nThe default configuration of the `skip` option is:\n\n```javascript\n// Other modules, then...\n'@apostrophecms/redirect': {\n  options: {\n    skip: [ /\\/api\\/v1\\/.*/ ]\n  }\n}\n```\n\nIf you wish to skip other patterns, we recommend keeping the default one as it speeds up API calls.\n\n## Usage\n\nWhile logged in as an admin, click the \"Redirects\" button. A list of redirects appears, initially empty. Add as many redirects as you like. The \"from\" URL must begin with a `/`. The \"to\" URL may be anything and need not be on your site. The \"description\" field is for your own convenience.\n\nBy default a redirect includes any query string (the `?` and whatever follows it, up to but not including any `#`) on incoming requests when matching for redirection. You can toggle the \"ignore query string when matching\" option in a redirect definition to ignore query strings on incoming requests and only match on the base URL path. A redirect that does not use this option will always match first, so you can match various specific query strings and then have a fallback rule for other cases.\n\nBe aware that each redirect is live as soon as you save it and that it is possible to make a mess with redirects. In a pinch, you can remove unwanted redirects via the MongoDB command line client (look for `{ type: \"@apostrophecms/redirect\" }` in the `aposDocs` collection in MongoDB).\n\nAlso be aware that Apostrophe already creates \"soft redirects\" every time you change the slug of a page, provided the page has been accessed at least once at the old URL. So you shouldn't need manually created \"hard redirects\" in that situation.\n\n## Extending the module\n\n### Providing a fallback handler\n\nIf you wish to handle redirects in another way when this module does not find a match, you can do so by listening for the `@apostrophecms/redirect:noMatch` event. This event handler receives `req, result`. To issue a redirect, set `result.redirect` in your event handler. To issue a \"raw\" redirect to which any sitewide prefix is not appended automatically, set `result.rawRedirect` in your event handler. You can also set `result.status` to match your need as the status code of the redirection, default is `302`.   \nIf you wish to alter the target url when a redirection is about to come, like for example to change the domain, you can listen to the `@apostrophecms/redirect:beforeRedirect`. This event handler receives `req, result`. `result` will have two properties that you can alter before the redirection: `status` and `url`. **Do not** call `req.res.redirect()` yourself in your event handler in those two cases.\n\nFor example:\n\n```javascript\n// modules/redirect-fallback/index.js\nmodule.exports = {\n  handlers(self) {\n    return {\n      '@apostrophecms/redirect:noMatch': {\n        // will be awaited, you can do queries here if needed\n        async fallback(req, result) {\n          if (req.url.match(/pattern/)) {\n            result.redirect = '/destination';\n          }\n        }\n      }\n    }\n  }\n}\n```\n\n### Preempting the redirect module\n\nIf your goal is to preempt this module by making a decision to redirect differently in some cases before this module looks for a match, register your own middleware and perform the redirect there. Use `before` to specify that your own module's middleware comes first.\n\nFor example:\n\n```javascript\n// modules/early-redirect/index.js\nmodule.exports = {\n  middleware(self) {\n    return {\n      earlyRedirect: {\n        before: '@apostrophecms/redirect',\n        middleware(req, res, next) {\n          if (req.url.match(/pattern/)) {\n            return res.redirect('/destination');\n          } else {\n            return next();\n          }\n        }\n      }\n    };\n  }\n};\n```\n\n### Executing the middleware sooner\n\nBy default the middleware of this module that checks for redirect is executed depending on the place of this module in your modules configuration.   \nYou can choose to execute it before any other module by setting the `before` option, indicating before which module middleware this one should run (for example `@apostrophecms/global`).   \nNote that by doing this, the above preemption will not work anymore.   \n\n\n## Redirecting to other locales\n\nIt's possible to redirect from one locale to another one, with external redirections, \nsince you manually define the url to redirect to.\n\nAs for internal redirects (relationships with pages), this works across locales as well, \nbut keep in mind that you will only see the internal redirects that target the current locale when managing redirects. \nTo find redirects that target an internal page in a different locale, switch locales before viewing \"Manage Redirects.\"\n\nA note for developers: a query builder called `currentLocaleTarget` hides redirects that have relationships to other locales (different from the current one).\nIf you want to get all redirects whatever the locale of their internal redirects you can undo this behavior using the query builder:\n```javascript\nconst redirects = await self.apos.modules['@apostrophecms/redirect']\n    .find(req)\n    .currentLocaleTarget(false)\n    .toArray();\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapostrophecms%2Fredirect","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapostrophecms%2Fredirect","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapostrophecms%2Fredirect/lists"}