{"id":16170755,"url":"https://github.com/holtwick/zerva","last_synced_at":"2025-03-16T10:31:08.577Z","repository":{"id":57148385,"uuid":"384222563","full_name":"holtwick/zerva","owner":"holtwick","description":"🌱 Simple event driven server","archived":false,"fork":false,"pushed_at":"2024-04-24T11:25:46.000Z","size":5711,"stargazers_count":18,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-05-16T23:51:44.503Z","etag":null,"topics":["cors","event-driven","express","http","https","javascript","nodejs","server","services","typed","typescript","zeed","zerva"],"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/holtwick.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["holtwick"]}},"created_at":"2021-07-08T19:00:09.000Z","updated_at":"2024-05-31T18:10:47.309Z","dependencies_parsed_at":"2024-01-06T22:24:59.120Z","dependency_job_id":"6448d5f6-a1ca-4952-ba4a-2bc8408a6b85","html_url":"https://github.com/holtwick/zerva","commit_stats":{"total_commits":315,"total_committers":2,"mean_commits":157.5,"dds":"0.0031746031746031633","last_synced_commit":"84ea713b066c6da2653f60eb72af6599393c5a00"},"previous_names":[],"tags_count":505,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holtwick%2Fzerva","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holtwick%2Fzerva/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holtwick%2Fzerva/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holtwick%2Fzerva/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/holtwick","download_url":"https://codeload.github.com/holtwick/zerva/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221662685,"owners_count":16859731,"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":["cors","event-driven","express","http","https","javascript","nodejs","server","services","typed","typescript","zeed","zerva"],"created_at":"2024-10-10T03:19:34.742Z","updated_at":"2024-10-27T10:25:21.733Z","avatar_url":"https://github.com/holtwick.png","language":"TypeScript","readme":"# 🌱 Zerva\n\n**Minimal event driven web service infrastructure.**\n\n## Get started\n\nSet up your first project using this [template](https://github.com/holtwick/zerva-project-template/generate).\n\n## How it works\n\nIt all starts with the `context` which is the common ground for any **module** we use or create. It serves as a hub/bus for emitting and listening on **events**.\n\nUsually you would start to build a server like this:\n\n```ts\nimport { useHttp } from '@zerva/http'\n\nuseHttp({\n  port: 8080\n})\n```\n\n`serve` itself is a **module** that i.e. it is a function working on **context**. It takes a function to call other modules and provides a common lifecycle by emitting `serveInit` and `serveStart`. These are the entry points for other services.\n\n`useHttp` for example will set up an [express]() server and start it on `serveStart`. It will emit `httpInit` before it starts and `httpRunning` when it is ready.\n\n\u003e By convention, we add `use` to module initializer to be able to identify them at first glance.\n\nYou can write your own module which can use `httpInit` to add some listeners:\n\n```ts\nfunction useCounter() {\n  let counter = 0\n  on('httpInit', ({ get }) =\u003e {\n    get('/counter', () =\u003e `Counter ${counter++}`)\n  })\n}\n```\n\nAs you can see a **module** is just a function connecting itself to the **context**. But where is the context? Well `context` is set globally. Similarly, as for Vue and React our helper routines like `on` or `emit` make use of it. This is a great simplification while still being a robust approach.\n\n\u003e If you want to use multiple **contexts** just wrap the code using it into `withContext(context, () =\u003e { /* your code */ })`.\n\nOn `httpInit` we make use of the http-modules specific `get` helper to answer to http-requests on `/counter`.\n\nTo make sure the `http` module is around as well in our context, it is good practice to register oneself and tell about dependencies using `register`:\n\n```ts\nfunction useCounter() {\n  register('counter', ['http'])\n  let counter = 1\n  on('httpInit', ({ get }) =\u003e {\n    get(\n      '/',\n      () =\u003e `Counter ${counter++}.\u003cbr\u003e\u003cbr\u003eReload page to increase counter.`\n    )\n  })\n  return {\n    getCounter: () =\u003e counter,\n  }\n}\n```\n\nAs you can see we can also return some custom data or functions from our module, like `getCounter` in our case.\n\nThat's basically it!\n\n## Command line convenience\n\nFor convenience, you can use the `zerva` command line tool. It is based on [estrella](https://github.com/rsms/estrella) and translates your Typescript code on the fly without further configuration. It also watches for changes and restarts the server immediately. To build add `build` as first argument. The last argument can point to the entry file (Javascript or Typescript), otherwise `src/main.ts` will be used.\n\nIn your `package.json` you might want to add these lines:\n\n```json\n{\n  \"scripts\": {\n    \"start\": \"zerva\",\n    \"build\": \"zerva build\",\n    \"serve\": \"node dist/main.cjs\"\n  }\n}\n```\n\n## Docker\n\nZerva integrates perfectly with Docker. Learn more at [demos/docker](https://github.com/holtwick/zerva/demos/docker).\n\n## GitHub Templates\n\nTo get started, you can use these GitHub Templates:\n\n- [Create your own Zerva module](https://github.com/holtwick/zerva-module-template/generate)\n- [Create your own Zerva project](https://github.com/holtwick/zerva-project-template/generate)\n\n## External Modules\n\n- [@zerva/bin](./zerva-bin) - CLI tool\n- [@zerva/core](./zerva-core) - The core of it all\n- [@zerva/vite](./zerva-vite) - Vite integration\n- [@zerva/plausible](./zerva-plausibe) - Visitors tracking using plausible.js\n- [@zerva/umami](./zerva-umami) - Visitors tracking using umami.js\n- [@zerva/websocket](./zerva-websocket) - Websockets\n- [@zerva/socketio](./zerva-socketio) - Websockets using socket.io\n- [@zerva/exit](./zerva-exit) - CTRL-C support\n- [@zerva/qrcode](./zerva-qrcode) - Show QR Code for external IP addresses to simplify mobile development\n\n## Advanced Topics\n\n### Conditional building\n\nZerva uses [esbuild](https://esbuild.github.io) to create both the development server code and the production code. You can take advantage of conditional building using [defines](https://esbuild.github.io/api/#define). This can be used to have code that avoids certain imports or otherwise unneed stuff in production mode. I.e. in your code you can do stuff like this:\n\n```ts\nif (ZERVA_DEVELEPMENT) {\n  /* do something */\n}\n```\n\nValid defines are:\n\n- `ZERVA_DEVELOPMENT` is `true` when started as `zerva`\n- `ZERVA_PRODUCTION` is `true` when started as `zerva build`\n\nFor better compatibility the defines can also be accessed as `process.env.ZERVA_DEVELOPMENT` and `process.env.ZERVA_PRODUCTION`.\n\n## Minimal Requirements\n\n- Node: 16\n- JS target: es2022\n\nSee [tsconfig/bases](https://github.com/tsconfig/bases) to learn details about the configuration considerations.\n\n## Related Projects\n\n- [zeed](https://github.com/holtwick/zeed) - Helper lib providing the logging for server\n- [zeed-dom](https://github.com/holtwick/zeed-dom) - Lightweight offline DOM\n","funding_links":["https://github.com/sponsors/holtwick"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fholtwick%2Fzerva","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fholtwick%2Fzerva","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fholtwick%2Fzerva/lists"}