@vactorynext/console

Admin console and feature flags for Vactory Next apps.

Requirements

@vactorynext/core ≥ 3.1.0 is required. That release (and above) provides the webpack alias @vactorynext/console/project-flags → app-root flags.ts, and emits .runtime/project-flags.js for custom servers. Older core will not resolve project flags correctly — upgrade core before or together with installing this package.

This package cannot run alone. Every app must provide:

apps/<project>/flags.ts

exporting defaultFlags (system flag defaults). Runtime values are stored in database/flags-db.json (created automatically). Keep flags.ts outside database/ so an Easypanel/Docker volume on database/ does not hide defaults.

Editing flags.ts in a fork (published npm package) is the source of truth: the loader reads app-root flags.ts first, then falls back to .runtime/project-flags.js (Docker / no jiti). New or changed flag definitions are merged into flags-db.json on the next request (saved values in the DB are kept). Reload /admin after editing; a Next rebuild still refreshes .runtime/project-flags.js for production.

Next apps using @vactorynext/core createNextConfig get an automatic webpack alias:

@vactorynext/console/project-flags → flags.ts (app root; legacy database/flags.ts still accepted)

That static alias is required (no dynamic require / jiti) so Webpack does not warn about critical dependencies.

Entry points

| Import | Use | |--------|-----| | @vactorynext/console/client | FlagBagProvider, useFlags, useFlag (browser-safe) | | @vactorynext/console/server | getServerSidePropsFlags, updateFlag, createFlag, getFlags, syncFlags | | @vactorynext/console/flag-types | Flag type, FLAG_NAMESPACE_SPERARATOR (for your flags.ts) | | @vactorynext/console/admin | Admin page + getServerSideProps | | @vactorynext/console/api-route | createApiRoute for /api/admin/flags | | @vactorynext/console/middleware | Shield / IP helpers | | @vactorynext/console/components-resolver | addComponent for admin UI injections |

Do not import @vactorynext/console/lib/database/flags — use /server.

Project flags.ts example

import type { Flag } from "@vactorynext/console/flag-types"
import { FLAG_NAMESPACE_SPERARATOR } from "@vactorynext/console/flag-types"

export const defaultFlags: Flag[] = [
  {
    name: `system${FLAG_NAMESPACE_SPERARATOR}shield`,
    fieldLabel: "Enable shield",
    value: false,
    isSecure: false,
    type: "boolean",
    group: "shield",
    namespace: "system",
  },
  // ...
]

Widget admin flags still come from .runtime/widgets.config.json (Webpack) and are merged by the package.

Starter wiring

• pages/_app.jsx → /client
• pages/admin/[[...admin]].jsx → /admin + /components-resolver
• pages/api/admin/flags.js → /api-route
• SSR / offline → /server

Publish

See PUBLISH.md.

Tailwind

Admin theme content should include package sources, e.g.:

"../../node_modules/@vactorynext/console/src/**/*.{js,jsx,ts,tsx}"

Console UI / admin theme use stock Tailwind palettes only (no CSS-variable brand colors). In themes/admin/tailwind.config.js, semantic names are aliases:

• primary → indigo
• error → red
• warning → amber
• success → green

So shared CSS like border-primary-500 still compiles, and colors look the same in every project.