https://github.com/phlare/node-edge-core
Node Edge Core is a reusable TypeScript service template for integration-facing services.
https://github.com/phlare/node-edge-core
edge-service fastify pino template typescript webhook zod
Last synced: 22 days ago
JSON representation
Node Edge Core is a reusable TypeScript service template for integration-facing services.
- Host: GitHub
- URL: https://github.com/phlare/node-edge-core
- Owner: phlare
- License: mit
- Created: 2026-03-07T06:58:21.000Z (4 months ago)
- Default Branch: develop
- Last Pushed: 2026-05-25T03:01:06.000Z (29 days ago)
- Last Synced: 2026-05-25T04:29:48.027Z (29 days ago)
- Topics: edge-service, fastify, pino, template, typescript, webhook, zod
- Language: TypeScript
- Homepage:
- Size: 521 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Node Edge Core
[](https://github.com/phlare/node-edge-core/actions/workflows/ci.yml)
[](https://github.com/phlare/node-edge-core/releases/latest)
[](https://nodejs.org)
[](https://www.typescriptlang.org)
[](LICENSE)
Reusable TypeScript service template for integration-facing services. This is a generic foundation — it contains no product logic, only service plumbing.
Intended for things like:
- Slack adapters
- MCP servers
- Webhook receivers
- Lightweight integration APIs
## Requirements
- Node 24+ (pinned in `.nvmrc`)
## Local Setup
```bash
# Install dependencies
npm install
# Copy env file and fill in values
cp .env.example .env
# Run the dev server (hot reload)
npm run dev
```
The service is available at `http://localhost:3001`.
## Running Tests
```bash
# Run all tests
npm test
# Run tests in watch mode
npm run test:watch
```
## Pre-commit Checks
```bash
# Format, lint, typecheck, and test
npm run precommit
```
## API Endpoints
| Method | Path | Description |
| ------ | ---------- | ------------ |
| GET | `/healthz` | Health check |
## Architecture
- **App factory**: `buildApp(opts?)` creates a configured Fastify instance — testable in isolation
- **Composition root**: `server.ts` is the only file that reads env vars
- **Env validation**: Zod schema with fail-fast on startup
- **Error handling**: `AppError` class → consistent `{ error: { code, message, details } }` envelope
- **Request logging**: Structured pino logs with request_id, method, url, status_code, duration_ms
- **Core API client**: Typed `CoreApiClient` for calling backend services (constructor injection, no env coupling)
See `docs/ARCHITECTURE.md` for detailed design and `docs/DECISIONS.md` for the decision log.
## Configuration
Copy `.env.example` to `.env`. Dev requires:
| Variable | Default | Description |
| ------------------- | ------- | --------------------------------------- |
| `PORT` | 3001 | HTTP port |
| `HOST` | 0.0.0.0 | Bind address |
| `LOG_LEVEL` | info | Pino log level |
| `CORE_API_BASE_URL` | — | Backend API URL (required) |
| `CORE_API_TOKEN` | — | Bearer token for backend API (required) |
## Related Templates
This is one of three reusable service templates. They share API conventions and response envelopes but are otherwise independent.
| Template | Purpose | Stack |
| ---------------------------------------------------------------- | ------------------------- | --------------------------------- |
| [**elixir-api-core**](https://github.com/phlare/elixir-api-core) | Core backend APIs | Elixir, Phoenix, PostgreSQL |
| **node-edge-core** (this repo) | Edge/integration services | TypeScript, Fastify, Zod |
| [**web-app-core**](https://github.com/phlare/web-app-core) | Frontend SPA | TypeScript, React, Vite, Tailwind |
Product 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.
This 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.
## Project Status
See `CHANGELOG.md` for the versioned task tracker.