Creating Services and Libraries
The CoW Protocol BFF monorepo uses NX generators to scaffold new projects with proper TypeScript, Docker, and configuration setup.
Available Generators
Three main generators are available:
| Command | Purpose |
|---|
yarn new:fastify | REST API services |
yarn new:node | Background workers, CLI tools |
yarn new:lib | Shared libraries |
Fastify API Services
Running the Fastify generator creates a complete API structure with:
- App configuration (
src/app/app.ts)
- Entry point (
src/main.ts)
- Docker setup
- ESLint settings
- Testing infrastructure
Route Organization
Keep route schemas in separate files (e.g., *.schemas.ts). Do not inline JSON schemas in route handlers.
Post-Generation Steps
- Add the new service to
docker-compose.yml with appropriate networking and environment configuration
- Update CI/CD pipeline configurations
- Configure environment variables
Node.js Applications
The Node.js generator supports:
- Background workers
- Message queue consumers
- Scheduled jobs
- CLI tools
Bootstrap Pattern
Applications typically include graceful shutdown handling:
import { logger } from '@cowprotocol/shared';
async function main() {
logger.info('Starting service...');
// Application logic here
process.on('SIGTERM', async () => {
logger.info('Shutting down gracefully...');
// Cleanup logic
process.exit(0);
});
}
main().catch((error) => {
logger.error({ err: error }, 'Fatal error');
process.exit(1);
});
Shared Libraries
Libraries enable code reuse across multiple applications.
Post-Generation Setup
- TypeScript path alias - Register in
tsconfig.base.json:
{
"paths": {
"@cowprotocol/my-library": ["libs/my-library/src/index.ts"]
}
}
- Public API - Define exports in
src/index.ts:
export { MyService } from './lib/my-service';
export { MyRepository } from './lib/my-repository';
export type { MyInterface } from './lib/types';
- Module boundaries - Follow these rules:
- Apps can import from libs
- Libs should only import from other libs
- Never create circular dependencies
Existing Libraries
The monorepo includes these shared libraries:
| Library | Purpose |
|---|
@cowprotocol/repositories | Data access layer |
@cowprotocol/services | Business logic |
@cowprotocol/shared | Utilities and types |
@cowprotocol/notifications | Notification templates |
@cowprotocol/abis | Smart contract ABIs |
Architecture Enforcement
NX enforces module boundaries to maintain clean architecture:
- Apps can import from libs
- Libs should only import from other libs
- Circular dependencies are prevented
Pre-Commit Checklist
Before committing changes, run all checks:
# Run tests
yarn test
# Run linter
yarn lint
# Build the project
yarn build
Last modified on March 4, 2026
