@verentis/template-application

Verentis App Template

A Nuxt 4 application template for building Verentis apps that run inside the workspace iframe.

Prerequisites

• Node.js 22+

Setup

1. Create a project from the CLI

Create a copy from the published npm template package:

verentis create application my-app

The package is published as @verentis/template-application; the repository is only the source used to publish that package.

Pushes affecting packages/application/ publish an independently versioned public package to npmjs through .github/workflows/publish-application-template.yml.

2. Install dependencies

npm install

3. Start development

# Copy the example env file
cp .env.example .env

# Edit .env with your API URL and key
# (only needed for standalone development outside the workspace)

npm run dev

The dev server starts at http://localhost:3300.

How It Works

The useVerentis() composable auto-detects the environment:

• iframe mode: When hosted by the workspace, it communicates via PostMessage to receive context (workspace ID, file path, access token) from the host.
• Standalone mode: When running independently (e.g., during development), it uses the API key from .env to authenticate directly with the Verentis API.

Project Structure

app/
  app.vue                       — Root component
  composables/useVerentis.ts    — SDK initialisation & context
  pages/index.vue               — Main app page
  assets/css/tailwind.css       — Tailwind + shadcn theme
  components/                   — Vue components
  lib/utils.ts                  — cn() utility
nuxt.config.ts                  — Nuxt configuration
components.json                 — shadcn-vue configuration
marketplace/                    — Marketplace logo and gallery artwork
CHANGELOG.md                    — Release notes displayed by the marketplace

App Manifest

This template uses a shared base manifest plus environment overlays:

• app-template.app.yaml keeps shared metadata, splash, entry points, MIME types, sandbox, OAuth client type, scopes, marketplace files, and packaging.
• environments/local.yaml sets spec.entry and spec.oauth.redirect-uris for local development. The template example is https://app-template.localtest.me:3300; replace the app name and port if needed.
• environments/production.yaml sets spec.entry and spec.oauth.redirect-uris for production. The template example, https://app-template.apps.verentis.dev, is a placeholder; replace it with your deployed host.

The Verentis CLI deep-merges the selected overlay onto the base manifest; objects merge, while arrays and scalars from the overlay replace the base. The base does not define spec.entry or spec.oauth.redirect-uris, and only those fields should differ per environment. spec.splash points to public/splash.svg; an entry point may override it, and relative splash URLs resolve against the selected iframe entry URL. Use --overlay <path> instead of --env only when selecting an explicit overlay file. After cloning the template, update the base manifest metadata and edit both overlay files for your app's local dev port and production host. Marketplace paths are resolved from the manifest directory and must remain below it; presentation files are catalog-only and should not be added to packaging.files.

Validate the merged manifest with:

verentis validate . --env local
verentis validate . --env production

Pack the app for a specific environment with:

verentis pack . --env local
verentis pack . --env production --set-version <version>

Manifest environments & publishing

CI (.github/workflows/publish-package.yml) packs the production overlay and publishes App Template-derived apps to the marketplace on every push to main, using version <major.minor>.<run-number>. Configure vars.VERENTIS_API_URL and the per-environment secrets.VERENTIS_API_KEY for your target environment before publishing. Additional environments such as uat or sprint can be added by creating environments/<env>.yaml and wiring the corresponding API key; sprint is expected to be published manually because its API key rotates each deploy.

Scripts

CI / GitHub Actions

The publish workflow requires vars.VERENTIS_API_URL and secrets.VERENTIS_API_KEY for the environment you publish to.

License

UNLICENSED — proprietary software.