{"id":28092433,"url":"https://github.com/curveball/browser","last_synced_at":"2025-05-13T13:14:47.074Z","repository":{"id":37174247,"uuid":"139493374","full_name":"curveball/browser","owner":"curveball","description":"A HAL browser middleware for node.js","archived":false,"fork":false,"pushed_at":"2025-04-05T02:13:18.000Z","size":2897,"stargazers_count":45,"open_issues_count":22,"forks_count":5,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-05-13T13:14:31.727Z","etag":null,"topics":["api","curveball","hacktoberfest","hal","hateaos","html","middleware","weblinking"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/curveball.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","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,"zenodo":null}},"created_at":"2018-07-02T20:50:53.000Z","updated_at":"2025-04-05T02:13:21.000Z","dependencies_parsed_at":"2024-01-24T23:28:08.985Z","dependency_job_id":"0ffff32d-c7b4-4c85-9d3f-30aaec0bac0f","html_url":"https://github.com/curveball/browser","commit_stats":{"total_commits":469,"total_committers":12,"mean_commits":"39.083333333333336","dds":0.07249466950959493,"last_synced_commit":"9f2245facb9b3f370593c222cf01fff856299b29"},"previous_names":["evert/hal-browser"],"tags_count":113,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curveball%2Fbrowser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curveball%2Fbrowser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curveball%2Fbrowser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curveball%2Fbrowser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/curveball","download_url":"https://codeload.github.com/curveball/browser/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253948503,"owners_count":21988961,"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":["api","curveball","hacktoberfest","hal","hateaos","html","middleware","weblinking"],"created_at":"2025-05-13T13:14:46.358Z","updated_at":"2025-05-13T13:14:47.063Z","avatar_url":"https://github.com/curveball.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"Curveball Browser\n=================\n\nThis package provides a middleware that automatically turns JSON responses\nfrom an API into HTML responses.\n\nIt will do so by looking if the API was accessed by a HTTP client that prefers\nHTML. Browsers do this by sending an `Accept: text/html` header.\n\nIf this middleware spots this, it will kick in and auto-generate a great looking\nHTML document.\n\nIf this header was not provides, this middleware does nothing.\n\nIt automatically decorates the following formats:\n\n* `application/json`\n* `application/problem+json`\n* `application/hal+json`\n* `text/markdown`\n* `text/csv`\n* `application/prs.hal-forms+json`\n* `application/vnd.siren+json`\n\nScreenshot\n----------\n\nAn example. If an API normally returns the following HAL format:\n\n```json\n{\n  \"_links\": {\n    \"self\": { \"href\": \"/testing\" },\n    \"previous\": {\n      \"href\": \"/testing/?page=1\",\n      \"title\": \"Previous page\"\n    },\n    \"next\": {\n      \"href\": \"/testing/?page=2\",\n      \"title\": \"Next page\"\n    },\n    \"author\": {\n      \"href\": \"https://evertpot.com\",\n      \"title\": \"Evert Pot\"\n    },\n    \"help\": {\n      \"href\": \"https://google.com/\",\n      \"title\": \"Google it\"\n    },\n    \"search\": {\n      \"href\": \"https://google.com/{?q}\",\n      \"templated\": true\n    },\n    \"edit\": { \"href\": \"/testing\" },\n    \"create-form\": { \"href\": \"/testing\" },\n    \"my-link\": {\n      \"href\": \"/foo-bar\",\n      \"title\": \"Custom link\"\n    },\n    \"alternate\": [\n      {\n        \"href\": \"/testing/markdown\",\n        \"type\": \"text/markdown\",\n        \"title\": \"Markdown test\"\n      },\n      {\n        \"href\": \"/testing/csv\",\n        \"type\": \"text/csv\",\n        \"title\": \"Csv test\"\n      },\n      {\n        \"href\": \"/testing/rss\",\n        \"type\": \"application/rss+xml\",\n        \"title\": \"RSS\"\n      },\n      {\n        \"href\": \"/testing/rss\",\n        \"type\": \"application/atom+xml\",\n        \"title\": \"Atom\"\n      }\n    ],\n    \"code-repository\": { \"href\": \"https://github.com/evert/hal-browser\" },\n    \"redirect-test\": { \"href\": \"/redirect-test\" }\n  },\n  \"msg\": \"Hello world!\",\n  \"version\": \"0.5.0\",\n  \"name\": \"test resource!\"\n}\n```\n\nThe browser will automatically convert it to this HTML format:\n\n![Screenshot from 0.9.1](https://github.com/curveball/browser/blob/main/screenshots/0.9.1.png)\n\nThis screenshot is an example of the browser automatically formatting a .csv\nand parsing HTTP `Link` headers:\n\n![Screenshot from 0.9.1](https://github.com/curveball/browser/blob/main/screenshots/0.9.1-csv.png)\n\nThe following example converts this:\n\n```json\n{\n  \"_links\": {\n    \"self\": {\n      \"href\": \"/testing/form\"\n    },\n    \"up\": {\n      \"href\": \"/testing\",\n      \"title\": \"Back to testing home\"\n    },\n    \"my-form\": {\n      \"href\": \"/testing/form{?startDate}{?endDate}\",\n      \"title\": \"Search by date range\",\n      \"templated\": true\n    }\n  }\n}\n```\n\nAnd automatically turns the templated link into a form:\n\n![Screenshot from 0.9.1](https://github.com/curveball/browser/blob/main/screenshots/0.9.1-form.png)\n\n\nInstallation\n------------\n\n    npm install @curveball/browser\n\n\nGetting started\n---------------\n\n```typescript\nimport { Application } from 'curveball/@core';\nimport browser from '@curveball/browser';\n\nconst app = new Application();\napp.use(browser({}));\n```\n\n\n### Options\n\nThe halBrowser function takes an options object, which can take the following\nsettings:\n\n* `title` - Change the main title.\n* `theme` - `curveball` by default, but `lfo` and `spicy-oj` are also provided.\n* `stylesheets` - Provide your own stylesheets. This is an array of strings.\n  these are relative urls, and they are automatically expanded based on the\n  `assetBaseUrl` setting.\n* `navigationLinks` - Specify (or remove) links that show up in the top\n  navigation.\n* `serveAssets` - by default the browser plugin will also take responsibility\n  for serving icons and stylesheet. If you're hosting these assets elsewhere,\n  set this to `false`.\n* `defaultLinks` - A list of links that will show up by default, whether or not\n  they were specified by the API. By default a `home` link is added here.\n* `hiddenRels` - List of relationship types that will be hidden from the user by\n  default. This can be used for links that are simply not interesting for a human\n  to see. (default: `['self', 'curies']`.\n* `fullBody` - If turned on, full JSON bodies are always rendered. This can also\n  be turned on during runtime by adding a `?_browser-fullbody` query parameter.\n* `allLinks` - By default the Browser will hide links from the 'Links' table\n  that will be rendered as 'navigation buttons', forms (templated links), or are\n  considered special (the 'self' link). While this might be a nicer interface\n  for an average user browsing the hypermedia graph, as a developer you might\n  just want to see all the links.\n\nExample:\n\n```javascript\napp.use(browser({\n  title: 'My API',\n  stylesheets: [\n    '/my-stylesheet.css',\n  ],\n\n  // This should end with a / generally.\n  assetBaseUrl: 'http://some-cdn.example.org/',\n\n  navigationLinks: {\n    // Create new 'author' button\n    'author' : {\n      // optional css class, by default this will be `rel-author`\n      cssClass: 'rel-blabla',\n\n      // Optional title to show when hovering over button\n      defaultTitle: 'Click me',\n\n      // Override icon. Also optional\n      icon: 'icons/foobar.svg',\n\n      // Either 'header' (default) or 'pager'\n      position: 'header'\n\n      // Set the order. Lower is earlier. Default is 0.\n      priority: -100,\n\n    },\n    // passing 'true' will use default setting for the button\n    'help' : true,\n\n    // passing 'null' will remove the icon, if it was a default icon\n    'up': null,\n  },\n\n  defaultLinks: [\n    // Every page will have a 'help' link\n    {\n      rel: 'help',\n      href: 'https://example.org/help',\n      title: 'Support',\n    }\n  ],\n});\n```\n\nFuture features\n---------------\n\n* Add a link to allow the user to see the raw format.\n* Show metadata, such as `Last-Modified`\n\n[1]: https://github.com/curveballjs/core\n[2]: https://expressjs.com/\n[3]: https://koajs.com/\n[4]: https://github.com/isagalaev/highlight.js/\n[5]: https://github.com/evert/hal-browser-express/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcurveball%2Fbrowser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcurveball%2Fbrowser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcurveball%2Fbrowser/lists"}