Veap and Next.js solve different layers of an application.
- Next.js owns the web application shell: App Router files, React rendering, route handlers, Server Components, client boundaries, deployment integration and the HTTP server.
@veap/kernelowns a reusable application lifecycle, dependency-injection container, service-provider registration, configuration, events, cache contracts, logging, and standardized error/result utilities.- Optional Veap packages provide database access, authentication, plugins, localization, mail, settings and storage.
What Veap does not automatically do#
The eight repositories documented here do not establish a replacement for next dev, next build, or next start. They do not define the standard Next.js app/ directory for you, nor do they imply that every package works in every runtime. Continue using the supported Next.js toolchain.
When to add a package#
| Requirement | Package |
|---|---|
| Shared service container and boot lifecycle | @veap/kernel |
| ORM and migrations | @veap/database |
| Users, sessions and permissions | @veap/auth |
| Pluggable admin/UI and plugin route tree | @veap/plugins |
| ICU translations and locale negotiation | @veap/intl |
| Email delivery | @veap/mail |
| Runtime-editable key/value settings | @veap/settings |
| Local or custom file provider | @veap/storage |
Add a package only when you need its capabilities. Read the package-specific runtime and peer-dependency notes before importing its entry points.
Behaviour delta#
Next.js owns the renderer, the file routing and the build. Veap packages add the application layer around requests - not instead of them.
| Concern | Native Next.js | Next.js with Veap |
|---|---|---|
| Lifecycle | No shared container or boot step | @veap/kernel: providers registered once, resolved from IoC |
| Routing | app/ files only | @veap/plugins: plugin route trees mounted through a catch-all |
| Layouts | Physical layout.tsx per segment | One site layout handed to the plugin provider for panel routes |
| Middleware | proxy.ts, no container access | Per-route middlewares (EnsuredUser) run in the request pipeline |
| Request state | Direct cookies() / headers() calls | COOKIE_STORE and REQUEST_CONTEXT bound by a transport provider |
| Configuration | Raw process.env reads | Validated config service that fails fast at boot |
| Errors | Ad-hoc throws per codebase | AppError and Result helpers with HTTP status mapping |
Inherited unchanged#
No transpiler, no runtime shim, no custom build command:
- React Server Components and Suspense streaming.
- Server Actions and the
"use client"/"use server"directives. - Route Handlers under
app/api/*. next.config.ts,next dev,next build,next start.public/assets andglobals.css.
Production remains next build followed by next start.
What behaves differently, by design#
bootstrap()is guarded per process and returns early duringphase-production-build, so builds never need a database; plugin-backed pages opt intoforce-dynamic.- The catch-all route is load-bearing: a physical page at the same URL shadows the plugin route.
- Enabling or disabling a plugin is a runtime operation persisted by the plugin registry, with migrations applied on boot.
- Route access is declared per page (
auth,roles,permissions) and always re-checked on the server. - Writes go through
transaction(); raw inserts from a connection handle are not the supported pattern.
For the request view of the same layering, see Inside a request.
