{"id":16092261,"url":"https://github.com/jh0rman/Cromo","last_synced_at":"2025-03-30T14:31:29.557Z","repository":{"id":181345351,"uuid":"665772738","full_name":"jh0rman/Cromo","owner":"jh0rman","description":"A tiny, fast \u0026 simple file-based router server for Bun 🧄","archived":false,"fork":false,"pushed_at":"2024-09-08T06:16:02.000Z","size":56,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-19T17:05:18.795Z","etag":null,"topics":["bun","express","filebaserouting","http"],"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/jh0rman.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2023-07-13T01:20:32.000Z","updated_at":"2024-12-09T15:18:31.000Z","dependencies_parsed_at":"2024-03-31T01:24:22.080Z","dependency_job_id":"581f03ac-826a-4798-b562-91beac5a5bb3","html_url":"https://github.com/jh0rman/Cromo","commit_stats":{"total_commits":40,"total_committers":1,"mean_commits":40.0,"dds":0.0,"last_synced_commit":"af4d31d64bf69d6966f89489bd2c66039e72e226"},"previous_names":["jhormanrus/pika","jhormanrus/cromo","qharin/cromo","jh0rman/cromo"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jh0rman%2FCromo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jh0rman%2FCromo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jh0rman%2FCromo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jh0rman%2FCromo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jh0rman","download_url":"https://codeload.github.com/jh0rman/Cromo/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245984558,"owners_count":20704794,"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":["bun","express","filebaserouting","http"],"created_at":"2024-10-09T16:06:22.376Z","updated_at":"2025-03-30T14:31:27.743Z","avatar_url":"https://github.com/jh0rman.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🎴 Cromo\n\nA tiny, fast \u0026 simple file-based router server for Bun 🧄\n\n[![NPM version][npm-version-image]][npm-url]\n[![install size](https://packagephobia.com/badge?p=cromo)](https://packagephobia.com/result?p=cromo)\n![NPM Downloads][npm-downloads-image]\n[![npm](https://img.shields.io/npm/l/cromo.svg)](https://spdx.org/licenses/MIT)\n[![Build status][build-image]][build-url]\n\n\u003c/div\u003e\n\n## Table of Contents\n\n- [Set up](#server-set-up)\n- [Router](#router-usage)\n- [Handlers](#handlers-usage)\n- [Middlewares](#middlewares)\n- [Start server](#start-the-server)\n- [Context object](#context-object)\n\n### Server set up\n\nTo get started with Cromo, you need to download the package using [Bun](https://bun.sh):\n\n```shell\nbun add cromo\n```\n\nNext, import and initialize Cromo in your code:\n\n```ts\nimport { Cromo } from 'cromo'\n\nconst cromo = new Cromo({\n  dir: './src/api'  // default: './api'\n  port: 5000        // default: Bun.env.PORT || 3000\n})\n```\n\n### Router usage \nCromo utilizes a file-based router system. By default, the router folder is named `api`, but you can change it by passing the dir option during initialization:\n\n``` ts\n// File structure example\n├── api\n│   ├── hello\n│   │   ├── [world]\n│   │   │   └── index.ts\n│   └── user\n│       ├── [name].ts\n│       └── index.ts\n└── index.ts\n```\n\n### Handlers usage\n\nInside the router files, you can write HTTP method handlers:\n\n```ts\n// api/hello/[world]/index.ts\nimport type { CromoContext, CromoHandler } from 'cromo'\n\n// handler for GET method\nexport const GET: CromoHandler = (context) =\u003e {\n  const { world } = context.params\n  return Response.redirect(`https://google.com/search?q=${world}`)\n}\n\n// default handler is called if there is no specific handler for the method\nexport default (context: CromoContext): Response =\u003e {\n  return Response.json(null, 404)\n}\n```\n\n### Middlewares\n\nThere are three ways to add middlewares in Cromo:\n\n1. Using `setMiddleware`: Simply call `setMiddleware` to add an array of middlewares to the server.\n\n```ts\n// index.ts\ncromo.setMiddleware([\n  (context, next) =\u003e {\n    console.log(\"middlewares called\")\n    return next(context)\n  },\n  ...\n])\n```\n\n2. Declaring `middlewares` const: Declare an array of middlewares in the router files as `middlewares` const.\n\n```ts\n// api/user/index.ts\nimport type { CromoHandler, CromoMiddleware } from 'cromo'\n\nexport const GET: CromoHandler = ({ responseInit }) =\u003e {\n  return Response.json({ name: 'John' }, responseInit)\n}\n\nexport const middlewares: CromoMiddleware[] = [\n  ({ responseInit }, next) =\u003e {\n    responseInit.headers = {\n      'Access-Control-Allow-Origin': '*'\n    }\n    return next(context)\n  }\n]\n```\n\n3. Declaring `[METHOD]_middlewares` const: Declare an array of middlewares in the router files as `[METHOD]_middlewares` const to apply middlewares to a specific method.\n\n```ts\n// api/user/[name].ts\nimport type { CromoHandler, CromoMiddleware } from 'cromo'\n\nexport const POST: CromoHandler = ({ params, responseInit }) =\u003e {\n  const { name } = params\n  return Response.json({ name }, responseInit)\n}\n\nexport const POST_middlewares: CromoMiddleware[] = [\n  ({ responseInit }, next) =\u003e {\n    responseInit.headers = {\n      'Access-Control-Allow-Origin': '*'\n    }\n    return next(context)\n  }\n]\n```\n\n### Start the server\n\nBy default, Cromo will listen to port `Bun.env.PORT`, and if it is not set, it will listen to port 3000. However, you can change it by passing the `port` option during initialization.\n\nHere is an example of starting the server:\n\n```ts\ncromo.start(port =\u003e {\n  console.log(`Listening on port ${port}`)\n})\n```\n\n### Context object\n\nIn Cromo, we use the context object to pass data between middlewares and handlers. It contains basic Web API objects like `Request`, `URL`, `ResponseInit`, and some useful properties like `matchedRoute`, `body`, `params`, `query`.\n\n```ts\nimport { MatchedRoute } from 'bun'\n\nexport interface CromoContext {\n  // request objects\n  request: Request\n  url: URL\n  matchedRoute: MatchedRoute\n  body: unknown\n  params: Record\u003cstring, string\u003e\n  query: Record\u003cstring, string\u003e\n  // response objects\n  responseInit: ResponseInit\n}\n```\n\n[npm-url]: https://www.npmjs.com/package/cromo\n[npm-version-image]: https://img.shields.io/npm/v/cromo\n[npm-downloads-image]: https://badgen.net/npm/dm/cromo\n[build-image]: https://github.com/jhormanrus/cromo/actions/workflows/publish.yml/badge.svg\n[build-url]: https://github.com/jhormanrus/cromo/actions/workflows/publish.yml\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjh0rman%2FCromo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjh0rman%2FCromo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjh0rman%2FCromo/lists"}