feat(adapter-nextjs): add Next.js adapter package with unified CLI

[dawidurbanski]

Summary

Introduces @universal-data-layer/adapter-nextjs, a framework adapter package that provides a unified CLI (udl-next) for running Universal Data Layer alongside Next.js applications. This replaces the need for manual shell concurrency or running separate terminals.

Before:

"scripts": {
  "dev": "udl & next dev",
  "build": "udl & npm run codegen && next build"
}

After:

"scripts": {
  "dev": "udl-next dev",
  "build": "udl-next build",
  "start": "udl-next start"
}

Related Issue

Closes #54

Type of Change

• New feature (non-breaking change that adds functionality)

What's Included

CLI Commands

Command	Behavior
udl-next dev	Run UDL + Next.js dev servers concurrently
udl-next build	Start UDL → run codegen → build Next.js (sequential)
udl-next start	Run UDL + Next.js production servers concurrently

Features

• Prefixed output: Console lines prefixed with [udl], [next], [codegen] for easy debugging
• Graceful shutdown: SIGINT/SIGTERM properly terminates all child processes
• Configurable ports: --port (UDL) and --next-port (Next.js) options
• Pass-through args: Use -- separator to pass arguments to Next.js
• Zero runtime dependencies: Uses native child_process module
• Programmatic API: Exports functions for custom integrations

Files Added

packages/adapter-nextjs/
├── bin/udl-next.js           # CLI entry point
├── src/
│   ├── cli.ts                # Argument parsing & command routing
│   ├── commands/
│   │   ├── dev.ts            # Concurrent dev servers
│   │   ├── build.ts          # Sequential build pipeline
│   │   └── start.ts          # Concurrent production servers
│   ├── utils/
│   │   ├── spawn.ts          # Process spawning utilities
│   │   ├── prefix-output.ts  # Output stream prefixing
│   │   └── wait-for-ready.ts # Port polling for server readiness
│   ├── types.ts              # TypeScript interfaces
│   └── index.ts              # Package exports
├── tests/unit/               # Unit tests (100% coverage)
├── README.md                 # Documentation
└── package.json

Files Modified

• examples/nextjs/package.json - Updated scripts to use udl-next
• commitlint.config.js - Added adapter-nextjs scope
• .gitignore - Updated coverage patterns

Checklist

Code Quality

• My code follows the project's style guidelines
• I have run npm run lint and fixed all issues
• I have run npm run typecheck with no errors
• I have run npm run fix to format my code

Testing

• I have run npm run test and all tests pass
• I have added tests for my changes
• Unit tests cover CLI parsing, spawn utilities, and all commands

Documentation & Changesets

• I have created a changeset using npm run changeset
• I have updated relevant documentation (README.md added)
• My commits follow the Conventional Commits specification

Final Checks

• I have self-reviewed my code
• I have tested my changes locally
• No breaking changes introduced

Testing Instructions

1. Install dependencies:

   npm install
   npm run build

2. Run unit tests:

   npm run test -- packages/adapter-nextjs

3. Test CLI in the Next.js example:

   cd examples/nextjs
   npm run dev      # Should start both UDL and Next.js
   # Press Ctrl+C   # Should gracefully stop both

4. Test build command:

   cd examples/nextjs
   npm run build    # Should run codegen then build Next.js

Usage Examples

# Development with default ports
udl-next dev

# Custom ports
udl-next dev --port 5000 --next-port 4000

# Pass args to Next.js
udl-next dev -- --turbo

# Production build
udl-next build

# Production servers
udl-next start

Additional Notes

• This is the first "adapter" package, establishing a pattern for future adapters (Remix, Astro, etc.)
• Uses native Node.js APIs only - no external dependencies
• The adapter is designed to be framework-agnostic internally, making future adapters straightforward to implement

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
universal-data-layer-nextjs	Ready	Preview, Comment	Dec 21, 2025 11:21am