N-SIDE WeFa Frontend Library

N-SIDE WeFa (Web Factory) is a Vue 3 toolkit that accelerates building cohesive product interfaces. It combines a component library, opinionated data layer helpers, internationalisation utilities, and CLI scripts so product teams can ship consistent experiences quickly.

• About
• Feature Highlights
• Installation
  • Install from npm
  • Install from a local build
  • Post-install tooling
• Using the library
  • Icons and the registry helper
• Development workflow
  • Core scripts
• Testing and quality gates
• Storybook and documentation
• Contributing
• Release process
• License
• Project status

About

The library is built on top of the following ecosystem:

• Vue 3 + Vite for fast DX
• PrimeVue and Tailwind for UI foundations
• Pinia for state management
• Vue I18n for localisation
• Axios and Hey-API for HTTP and schema tooling

A demo playground lives alongside the library so you can experiment locally while developing components.

Feature Highlights

• Rich component catalogue following the WeFa design language
• Reusable containers, router helpers, and data-client utilities for product scaffolding
• CLI (wefa-install) that bootstraps recommended project configuration
• Opinionated linting, formatting, and testing presets aligned with modern Vue best practices

Installation

Install from npm

npm install @nside/wefa
# or
pnpm add @nside/wefa
# or
yarn add @nside/wefa

Import the base styles once in your application (for example in main.ts):

import '@nside/wefa/style';

Install from a local build

Use this flow when testing unreleased changes from a cloned repository:

cd vue
npm install
npm run build
npm pack
# This outputs something like wefa-1.0.0.tgz

Then, in your consuming project:

npm install --force /absolute/path/to/wefa-1.0.0.tgz

Repeat the build-and-pack step whenever you change the library.

Post-install tooling

Run the bundled installer to copy optional helpers (AI prompts, configuration snippets, etc.) into your project:

npx wefa-install

Using the library

Import components and types directly from the package:

<script setup lang="ts">
import { WefaButton } from '@nside/wefa';
</script>

<template>
  <WefaButton label="Launch" />
</template>

Types live under the @nside/wefa/types export:

import type { WefaButtonProps } from '@nside/wefa/types';

The published package also includes the Backend-for-Frontend OpenAPI document at @nside/wefa/bff-openapi.

Theme preset

To apply the NSIDE Prime theme preset in your app:

import '@nside/wefa/style'
import PrimeVue from 'primevue/config'
import { nsidePrimeVueTheme } from '@nside/wefa'

app.use(PrimeVue, {
  theme: nsidePrimeVueTheme,
})

If you need to compose the PrimeVue config yourself, the lower-level exports are still available:

import { createNsideTheme, nsideThemeOptions } from '@nside/wefa'

app.use(PrimeVue, {
  theme: {
    preset: createNsideTheme(),
    options: nsideThemeOptions,
  },
})

createNsideTheme(primary) is still accepted for backward compatibility, but the argument is now ignored and the MMS-derived flagship theme is always returned.

Icons and the registry helper

WeFa uses Iconify under the hood. Bundled icon collections are registered automatically by calling setupDefaultIcons() inside src/iconRegistry.ts. If you need extra icons offline:

1. Install the relevant @iconify-json/<collection> package.
2. Register the collection at application bootstrap time.

import { registerCollections } from '@nside/wefa';
import mdi from '@iconify-json/mdi';

registerCollections(mdi);

If an icon is missing from the local registry Iconify transparently falls back to an online fetch.

Development workflow

Core scripts

From the vue/ directory:

| Command | Description | | --- | --- | | npm run dev | Start the demo application with hot-module replacement | | npm run build | Build the library bundle (includes type checking) | | npm run preview | Serve the built demo application | | npm run storybook | Launch Storybook for interactive documentation | | npm run build-storybook | Build the static Storybook site | | npm run lint / npm run lint-check | Auto-fix or check ESLint rules | | npm run format / npm run format-check | Run Prettier in write/check mode | | npm run test:package-types | Build the package, pack it, and verify published type declarations |

The project supports Node.js ^22.13.0 || >=24.0.0. Use the included .node-version or .nvmrc to align with CI; the repository currently pins 24.9.0.

Testing and quality gates

• Unit tests: npm run test:unit
• Unit tests in watch mode: npm run test:unit:watch
• End-to-end tests (Playwright against the demo app): npm run test:e2e
• Packaged declaration smoke test: npm run test:package-types

Aim for meaningful coverage when adding or changing components. Update or create MDX docs and Storybook stories alongside code changes.

Storybook and documentation

Storybook acts as both documentation and manual testing ground. Start it locally with npm run storybook. When contributing new components:

• create ComponentName.stories.ts showcasing variants
• add MDX docs if consumers need contextual guidance (src/components/ComponentName/ComponentName.mdx)
• keep props tables and accessibility notes up to date

The file src/README.mdx pulls in this README so Storybook stays in sync.

Contributing

We welcome pull requests! Start with CONTRIBUTE for the full workflow, environment setup, and quality gates. In short:

1. Align on the problem via an issue or discussion before large changes.
2. Keep linting, formatting, tests, and Storybook docs up to date.
3. Document UI changes with screenshots or recordings when helpful.
4. Run the commands listed in the contribution guide before pushing.

Release process

Versioning for this repository is managed from the monorepo root so vue, django, and bff stay aligned:

cd ..
python3 scripts/wefa_version.py bump <major|minor|patch>
# or:
python3 scripts/wefa_version.py set <x.y.z[-prerelease]>
cd vue
npm publish --access public

The version script expects SemVer for user input and tags. For prereleases, use alpha.<N>, beta.<N>, or rc.<N>; Python package files are automatically normalized to PEP 440 (a, b, rc) during updates.

Testing the library locally

If you want to test the library locally on a project using WeFa, you can do it with the following steps:

In the WeFa Folder

# Build the project
npm run build
# Generate a pack (this will output a .tgz file)
npm pack

In the project folder that uses WeFa

# Install the packed dependency
npm i /ABSOLUTE_PATH_TO_THE_PACK/nside-wefa-0.3.0.tgz