@appframework/vue

Vue components and TypeScript libraries for appframework.

Installation

npm install @appframework/vue

Peer dependencies

The UI is built entirely on bootstrap-vue-next. Host applications must install bootstrap, bootstrap-vue-next and register the plugin:

import 'bootstrap/dist/css/bootstrap.min.css'
import 'bootstrap-vue-next/dist/bootstrap-vue-next.css'
import { createBootstrap } from 'bootstrap-vue-next'

app.use(createBootstrap())

src/lib/rest.ts raises toasts through useToast(), so the app must also render bootstrap-vue-next's orchestrator — wrap the root template in <BApp> (or mount <BToastOrchestrator />), otherwise those toasts are silently dropped.

Usage

Components

<script setup>
import { BinaryDataImage, ListComponent } from '@appframework/vue';
</script>

<template>
  <BinaryDataImage :upload-path="'/rest/binary_data'" />
  <ListComponent :items="items" />
</template>

Defining extra columns on ListComponent

ListComponent renders a name column and an action column. Additional columns are declared with the extra-fields prop, using bootstrap-vue-next's table field descriptors. They are inserted between the name and action columns.

Custom rendering uses the #head(<key>) and #cell(<key>) slots, which are forwarded verbatim to the underlying BTable:

<script setup lang="ts">
import type { TableFieldRaw } from 'bootstrap-vue-next'

const extraFields: TableFieldRaw<User>[] = [
  { key: 'login', label: 'Login', sortable: true },
  { key: 'roles', label: 'Roles' },
]
</script>

<template>
  <ListComponent type="user" :stub="stub" :extra-fields="extraFields">
    <template #cell(roles)="{ item }">
      <span v-for="role in (item as User).roles" :key="role">{{ role }}</span>
    </template>
  </ListComponent>
</template>

Sorting is performed server side, so marking a field sortable is enough — the component turns the click into a new query.

Library Functions

import { getExisting, saveNew } from '@appframework/vue';

// Get data from API
const data = await getExisting('your-dto');

// Save new data
await saveNew('your-dto', newData);

Migrating from the PrimeVue-based releases (breaking)

PrimeVue, PrimeIcons and PrimeLocale have been removed; the library now uses bootstrap-vue-next exclusively. Host applications must drop app.use(PrimeVue, …) and the @primeuix/themes preset, and register createBootstrap() instead. Any --p-* design-token overrides no longer apply — style with Bootstrap variables.

ListComponent: #header-extra replaced by extra-fields

Extra columns used to be passed as PrimeVue <Column> children through the #header-extra slot. BTable declares columns through a fields array instead of accepting column components, so that slot is gone.

<!-- before -->
<ListComponent type="user" :stub="stub">
  <template #header-extra>
    <Column header="Login" sortable field="login" />
    <Column header="Roles">
      <template #body="{ data }">{{ data.roles.join(', ') }}</template>
    </Column>
  </template>
</ListComponent>

<!-- after -->
<ListComponent
  type="user"
  :stub="stub"
  :extra-fields="[
    { key: 'login', label: 'Login', sortable: true },
    { key: 'roles', label: 'Roles' },
  ]"
>
  <template #cell(roles)="{ item }">{{ item.roles.join(', ') }}</template>
</ListComponent>

Notes:

• <Column header field sortable> becomes { key, label, sortable }; key doubles as the property read from the row and as the slot name.
• #body="{ data }" becomes #cell(<key>)="{ item }"; custom headers move from #header to #head(<key>).
• The slot props of #header-extra (pager, order) are gone. pager, order and fetchData are available through a template ref on the component instead.
• Columns whose keys are only known at runtime still work — declare the slots with a v-for, as RolesView does.

Other component replacements

| Removed | Now | | --- | --- | | <Password toggle-mask /> | PasswordInput (exported by this package) | | <Listbox multiple :option-label="fn" /> | BFormSelect multiple; resolve labels up front into {value, text} options | | <ColorPicker /> | ColorPickerComponent now wraps <BFormInput type="color">; the model is still a #-less hex string | | <FileUpload custom-upload @uploader> | BFormFile with v-model / @update:model-value | | pi pi-* icons | @iconify/vue with the bi: set | | usePrimeVue().config.locale | removed; bootstrap-vue-next localises per component prop |

Contributing

We welcome contributions to @appframework/vue! This section will help you get started with development.

Development Setup

1. Clone the repository

   git clone <repository-url>
   cd appframework-vue

2. Install dependencies

   npm install

3. Start the development server

   npm run demo

   This will start a Vite development server with a live demo of all components and functionality.

Demo Environment

The demo environment provides a complete testing playground for all components:

• Mock GraphQL and REST Server: The demo includes a fully functional mock GraphQL server (demo/mock-server.ts) and a mock REST server (demo/mock-rest.ts) that intercepts GraphQL and REST requests and provides test data

• Sample Data: Mock data is defined in demo/mock-data.ts, including support for:

  • User queries with pagination, sorting, and filtering in GraphQL
  • Realistic user data with roles and permissions
  • Error handling scenarios

• Component Testing: All components can be tested in isolation with the mock data, allowing you to:

  • Test different data scenarios
  • Verify component behavior without a real backend
  • Develop new features rapidly

Development Workflow

1. Run the demo: npm run demo to start the development environment
2. Make changes: Edit components in src/components/ or library functions in src/lib/
3. Test changes: The demo will hot-reload to show your changes immediately
4. Run tests: npm test to run the test suite
5. Check code quality: npm run check to run Biome linting and formatting

Project Structure

src/
├── components/     # Vue components
├── lib/            # TypeScript utility functions
├── locales/        # Internationalization files
└── views/          # Vue views/pages

demo/
├── mock-*.ts       # Mock server setup
└── *.vue           # Demo components and examples

Building

• Development build: npm run demo:build
• Production build: npm run build
• Preview build: npm run preview

Testing

• Run tests: npm test
• Coverage report: npm run coverage

The mock server setup makes it easy to test GraphQL-dependent components without needing a real backend, ensuring consistent and reliable development experience.