{"id":50484430,"url":"https://github.com/phlare/node-edge-core","last_synced_at":"2026-06-01T20:31:58.515Z","repository":{"id":342976836,"uuid":"1175057696","full_name":"phlare/node-edge-core","owner":"phlare","description":"Node Edge Core is a reusable TypeScript service template for integration-facing services.","archived":false,"fork":false,"pushed_at":"2026-05-25T03:01:06.000Z","size":533,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"develop","last_synced_at":"2026-05-25T04:29:48.027Z","etag":null,"topics":["edge-service","fastify","pino","template","typescript","webhook","zod"],"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/phlare.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"phlare","patreon":"phlare","open_collective":null,"ko_fi":"phlare","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":["https://throne.com/phlare","https://phlare-shop.fourthwall.com"]}},"created_at":"2026-03-07T06:58:21.000Z","updated_at":"2026-05-25T03:01:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/phlare/node-edge-core","commit_stats":null,"previous_names":["phlare/node-edge-core"],"tags_count":7,"template":true,"template_full_name":null,"purl":"pkg:github/phlare/node-edge-core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phlare%2Fnode-edge-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phlare%2Fnode-edge-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phlare%2Fnode-edge-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phlare%2Fnode-edge-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phlare","download_url":"https://codeload.github.com/phlare/node-edge-core/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phlare%2Fnode-edge-core/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33793033,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["edge-service","fastify","pino","template","typescript","webhook","zod"],"created_at":"2026-06-01T20:31:57.880Z","updated_at":"2026-06-01T20:31:58.500Z","avatar_url":"https://github.com/phlare.png","language":"TypeScript","funding_links":["https://github.com/sponsors/phlare","https://patreon.com/phlare","https://ko-fi.com/phlare","https://throne.com/phlare","https://phlare-shop.fourthwall.com"],"categories":[],"sub_categories":[],"readme":"# Node Edge Core\n\n[![CI](https://github.com/phlare/node-edge-core/actions/workflows/ci.yml/badge.svg)](https://github.com/phlare/node-edge-core/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/phlare/node-edge-core)](https://github.com/phlare/node-edge-core/releases/latest)\n[![Node](https://img.shields.io/badge/Node-24+-339933)](https://nodejs.org)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6)](https://www.typescriptlang.org)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n\nReusable TypeScript service template for integration-facing services. This is a generic foundation — it contains no product logic, only service plumbing.\n\nIntended for things like:\n\n- Slack adapters\n- MCP servers\n- Webhook receivers\n- Lightweight integration APIs\n\n## Requirements\n\n- Node 24+ (pinned in `.nvmrc`)\n\n## Local Setup\n\n```bash\n# Install dependencies\nnpm install\n\n# Copy env file and fill in values\ncp .env.example .env\n\n# Run the dev server (hot reload)\nnpm run dev\n```\n\nThe service is available at `http://localhost:3001`.\n\n## Running Tests\n\n```bash\n# Run all tests\nnpm test\n\n# Run tests in watch mode\nnpm run test:watch\n```\n\n## Pre-commit Checks\n\n```bash\n# Format, lint, typecheck, and test\nnpm run precommit\n```\n\n## API Endpoints\n\n| Method | Path       | Description  |\n| ------ | ---------- | ------------ |\n| GET    | `/healthz` | Health check |\n\n## Architecture\n\n- **App factory**: `buildApp(opts?)` creates a configured Fastify instance — testable in isolation\n- **Composition root**: `server.ts` is the only file that reads env vars\n- **Env validation**: Zod schema with fail-fast on startup\n- **Error handling**: `AppError` class → consistent `{ error: { code, message, details } }` envelope\n- **Request logging**: Structured pino logs with request_id, method, url, status_code, duration_ms\n- **Core API client**: Typed `CoreApiClient` for calling backend services (constructor injection, no env coupling)\n\nSee `docs/ARCHITECTURE.md` for detailed design and `docs/DECISIONS.md` for the decision log.\n\n## Configuration\n\nCopy `.env.example` to `.env`. Dev requires:\n\n| Variable            | Default | Description                             |\n| ------------------- | ------- | --------------------------------------- |\n| `PORT`              | 3001    | HTTP port                               |\n| `HOST`              | 0.0.0.0 | Bind address                            |\n| `LOG_LEVEL`         | info    | Pino log level                          |\n| `CORE_API_BASE_URL` | —       | Backend API URL (required)              |\n| `CORE_API_TOKEN`    | —       | Bearer token for backend API (required) |\n\n## Related Templates\n\nThis is one of three reusable service templates. They share API conventions and response envelopes but are otherwise independent.\n\n| Template                                                         | Purpose                   | Stack                             |\n| ---------------------------------------------------------------- | ------------------------- | --------------------------------- |\n| [**elixir-api-core**](https://github.com/phlare/elixir-api-core) | Core backend APIs         | Elixir, Phoenix, PostgreSQL       |\n| **node-edge-core** (this repo)                                   | Edge/integration services | TypeScript, Fastify, Zod          |\n| [**web-app-core**](https://github.com/phlare/web-app-core)       | Frontend SPA              | TypeScript, React, Vite, Tailwind |\n\nProduct apps are created _from_ these templates and then diverge freely with domain logic. They're designed to work together — a frontend built from web-app-core calls a backend API built from elixir-api-core, while edge services built from node-edge-core handle integrations.\n\nThis repo is intended to work as a standalone starting point. It does not require the companion templates to exist locally in the same directory. If you want to pair it with the related backend or frontend templates, use the GitHub repos above rather than assuming a shared workspace layout.\n\n## Project Status\n\nSee `CHANGELOG.md` for the versioned task tracker.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphlare%2Fnode-edge-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphlare%2Fnode-edge-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphlare%2Fnode-edge-core/lists"}