Greenforce

A Vue 3 plugin library that bundles the core building blocks used across our Vue applications: an authenticated API client, a dialog manager, a navigation/tab manager, a toast notification system, and a set of reusable mixins and errors.

Installation

Greenforce ships a compiled dist/ (ESM + CJS + .d.ts). No bundler configuration is needed for node_modules/greenforce. Add it to a Vue 3 app alongside its peer dependencies:

npm install greenforce
npm install @auth0/auth0-vue vue vue-i18n vue-logger-plugin vue-router vuetning

axios and uuid are pulled in automatically as runtime dependencies. Requires Node >= 18 to install.

Usage

Every manager is installed as a standard Vue plugin via a create* factory:

import { createApp } from "vue"
import {
    createApiClient,
    createDialogManager,
    createNavigationManager,
    createToastManager,
} from "greenforce"

import App from "./App.vue"
import router from "./router"
import i18n from "./i18n"
import { auth0 } from "./auth0"
import logger from "./logger"

const app = createApp(App)

app.use(auth0)
app.use(router)
app.use(i18n)
app.use(logger)

app.use(createApiClient({ auth0, logger }))
app.use(createDialogManager())
app.use(createNavigationManager({ router, i18n }))
app.use(createToastManager({ i18n }))

app.mount("#app")

createApiClient is idempotent: the first call caches the installer and the exported apiClient Axios instance; subsequent calls return the same installer regardless of new options.

Public API

Everything consumers can import lives in src/index.ts:

Installers

• createApiClient(options) — configures an Axios instance that injects Auth0 tokens and logs out the user on 401 responses.
• createDialogManager() — installs modal/dialog lifecycle management.
• createNavigationManager(options) — installs the tab-based navigation system on top of Vue Router.
• createToastManager(options) — installs the toast notification system.

Managers and classes

• ApiResponse — wrapper around Axios responses.
• DialogManager, NavigationManager, ToastManager — singleton managers exposed for direct use.
• Tab — represents an individual navigation tab.
• encodePath — helper from tab-parser for encoding navigation paths.
• VIEW_MODE — constants for navigation view modes.

Mixins

• ViewMixin — base functionality for views.
• ChildViewMixin — extends ViewMixin for nested/child views.
• InitializableMixin — provides an initialization lifecycle hook.

Errors

• ApiError — thrown by the API client for non-success responses; carries status and payload context.
• ArgumentNullError — guard error used for required-argument validation.

Shared instance

• apiClient: AxiosInstance — the Axios instance created by createApiClient. Available after the first createApiClient call.

Project structure

src/
  api-client/          Axios + Auth0 integration
  dialog-management/   Dialog/modal manager
  errors/              ApiError, ArgumentNullError
  mixins/              ViewMixin, ChildViewMixin, InitializableMixin
  navigation-management/ Tab-based navigation manager
  toast-management/    Toast notification manager
  index.ts             Public entry point

When adding a new public symbol, export it from src/index.ts or consumers will not see it.

Development

npm install
npm run typecheck   # tsc --noEmit against src/
npm run lint        # check for lint issues
npm run lint:fix    # auto-fix where possible
npm run test        # run Vitest suite
npm run test:watch  # Vitest in watch mode
npm run build       # tsup → dist/
npm run build:watch # tsup in watch mode

ESLint enforces 4-space indentation, no semicolons, trailing commas in multiline literals, Vue 3 essential rules, and the project's TypeScript config. TypeScript runs in strict mode.

Release

Every push to main publishes a new patch version to npm. CI (GitHub Actions, see .github/workflows/publish-npm.yml) runs typecheck + lint + test + build, then npm publish, then tags the commit v<version> and increments the REVISION_VERSION repository variable via the GitHub API.

Humans edit MAJOR_VERSION or MINOR_VERSION under the repo's Actions variables when a minor/major bump is warranted — the CI owns the patch number.

Operator failure modes:

• Publish succeeds but tag push fails: version exists on npm without a git tag. Create the tag manually on the relevant commit.
• Publish succeeds but the REVISION_VERSION bump fails: the next main push will retry the same version and npm publish will 403. Bump REVISION_VERSION in the repo's Actions variables manually once, then push.
• Publish fails: no tag, no bump. Next push retries with the same version number.

Requirements

• Vue 3.5+
• Node 18+
• Peer plugins: @auth0/auth0-vue, vue-router, vue-i18n, vue-logger-plugin, vuetning