{"id":13494119,"url":"https://github.com/bripkens/connect-history-api-fallback","last_synced_at":"2025-05-13T19:17:54.547Z","repository":{"id":8524688,"uuid":"10140491","full_name":"bripkens/connect-history-api-fallback","owner":"bripkens","description":"Fallback to index.html for applications that are using the HTML 5 history API","archived":false,"fork":false,"pushed_at":"2023-10-26T06:55:33.000Z","size":305,"stargazers_count":1837,"open_issues_count":15,"forks_count":142,"subscribers_count":25,"default_branch":"main","last_synced_at":"2025-05-12T21:04:13.221Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/bripkens.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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":"2013-05-18T11:36:19.000Z","updated_at":"2025-05-08T00:46:47.000Z","dependencies_parsed_at":"2024-06-18T11:00:45.441Z","dependency_job_id":"1e6ee651-fe55-437a-b6be-548a8922078d","html_url":"https://github.com/bripkens/connect-history-api-fallback","commit_stats":{"total_commits":86,"total_committers":16,"mean_commits":5.375,"dds":"0.39534883720930236","last_synced_commit":"6b58bc97d4a2ff2be0a68dc661df5c7857758a55"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bripkens%2Fconnect-history-api-fallback","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bripkens%2Fconnect-history-api-fallback/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bripkens%2Fconnect-history-api-fallback/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bripkens%2Fconnect-history-api-fallback/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bripkens","download_url":"https://codeload.github.com/bripkens/connect-history-api-fallback/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254010830,"owners_count":21999004,"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":[],"created_at":"2024-07-31T19:01:22.064Z","updated_at":"2025-05-13T19:17:54.521Z","avatar_url":"https://github.com/bripkens.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003econnect-history-api-fallback\u003c/h1\u003e\n\u003cp align=\"center\"\u003eMiddleware to proxy requests through a specified index page, useful for Single Page Applications that utilise the HTML5 History API.\u003c/p\u003e\n\n\u003ch2\u003eTable of Contents\u003c/h2\u003e\n\n\u003c!-- TOC depthFrom:2 depthTo:6 withLinks:1 updateOnSave:1 orderedList:0 --\u003e\n\n- [Introduction](#introduction)\n- [Usage](#usage)\n- [Options](#options)\n\t- [index](#index)\n\t- [rewrites](#rewrites)\n\t- [verbose](#verbose)\n\t- [htmlAcceptHeaders](#htmlacceptheaders)\n\t- [disableDotRule](#disabledotrule)\n\n\u003c!-- /TOC --\u003e\n\n## Introduction\n\nSingle Page Applications (SPA) typically only utilise one index file that is\naccessible by web browsers: usually `index.html`. Navigation in the application\nis then commonly handled using JavaScript with the help of the\n[HTML5 History API](http://www.w3.org/html/wg/drafts/html/master/single-page.html#the-history-interface).\nThis results in issues when the user hits the refresh button or is directly\naccessing a page other than the landing page, e.g. `/help` or `/help/online`\nas the web server bypasses the index file to locate the file at this location.\nAs your application is a SPA, the web server will fail trying to retrieve the file and return a *404 - Not Found*\nmessage to the user.\n\nThis tiny middleware addresses some of the issues. Specifically, it will change\nthe requested location to the index you specify (default being `/index.html`)\nwhenever there is a request which fulfills the following criteria:\n\n 1. The request is a `GET` or `HEAD` request\n 2. which accepts `text/html`,\n 3. is not a direct file request, i.e. the requested path does not contain a\n    `.` (DOT) character and\n 4. does not match a pattern provided in options.rewrites (see options below)\n\n## Usage\n\nThe middleware is available through NPM and can easily be added.\n\n```\nnpm install --save connect-history-api-fallback\n```\n\nImport the library\n\n```javascript\nvar history = require('connect-history-api-fallback');\n```\n\nNow you only need to add the middleware to your application like so\n\n```javascript\nvar connect = require('connect');\n\nvar app = connect()\n  .use(history())\n  .listen(3000);\n```\n\nOf course you can also use this piece of middleware with express:\n\n```javascript\nvar express = require('express');\n\nvar app = express();\napp.use(history());\n```\n\n## Options\nYou can optionally pass options to the library when obtaining the middleware\n\n```javascript\nvar middleware = history({});\n```\n\n### index\nOverride the index (default `/index.html`). This is the request path that will be used when the middleware identifies that the request path needs to be rewritten.\n\nThis is not the path to a file on disk. Instead it is the HTTP request path. Downstream connect/express middleware is responsible to turn this rewritten HTTP request path into actual responses, e.g. by reading a file from disk.\n\n```javascript\nhistory({\n  index: '/default.html'\n});\n```\n\n### rewrites\nOverride the index when the request url matches a regex pattern. You can either rewrite to a static string or use a function to transform the incoming request.\n\nThe following will rewrite a request that matches the `/\\/soccer/` pattern to `/soccer.html`.\n```javascript\nhistory({\n  rewrites: [\n    { from: /\\/soccer/, to: '/soccer.html'}\n  ]\n});\n```\n\nAlternatively functions can be used to have more control over the rewrite process. For instance, the following listing shows how requests to `/libs/jquery/jquery.1.12.0.min.js` and the like can be routed to `./bower_components/libs/jquery/jquery.1.12.0.min.js`. You can also make use of this if you have an API version in the URL path.\n```javascript\nhistory({\n  rewrites: [\n    {\n      from: /^\\/libs\\/.*$/,\n      to: function(context) {\n        return '/bower_components' + context.parsedUrl.pathname;\n      }\n    }\n  ]\n});\n```\n\nThe function will always be called with a context object that has the following properties:\n\n - **parsedUrl**: Information about the URL as provided by the [URL module's](https://nodejs.org/api/url.html#url_url_parse_urlstr_parsequerystring_slashesdenotehost) `url.parse`.\n - **match**: An Array of matched results as provided by `String.match(...)`.\n - **request**: The HTTP request object.\n\n\n### verbose\nThis middleware does not log any information by default. If you wish to activate logging, then you can do so via the `verbose` option or by specifying a logger function.\n\n```javascript\nhistory({\n  verbose: true\n});\n```\n\nAlternatively use your own logger\n\n```javascript\nhistory({\n  logger: console.log.bind(console)\n});\n```\n\n### htmlAcceptHeaders\nOverride the default `Accepts:` headers that are queried when matching HTML content requests (Default: `['text/html', '*/*']`).\n\n```javascript\nhistory({\n  htmlAcceptHeaders: ['text/html', 'application/xhtml+xml']\n})\n```\n\n### disableDotRule\nDisables the dot rule mentioned above:\n\n\u003e […] is not a direct file request, i.e. the requested path does not contain a `.` (DOT) character […]\n\n```javascript\nhistory({\n  disableDotRule: true\n})\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbripkens%2Fconnect-history-api-fallback","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbripkens%2Fconnect-history-api-fallback","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbripkens%2Fconnect-history-api-fallback/lists"}