@equinor/fusion-framework-cli

Fusion Framework CLI is a command-line tool for developing, building, and publishing applications and portal templates within the Fusion Framework ecosystem. It streamlines workflows, automates common tasks, and supports modern CI/CD pipelines.

What you can build:

• Fusion Applications: Interactive web apps that run within the Fusion Portal
• Portal Templates: Customizable portal configurations for different business contexts

Key capabilities:

• Template-based app creation: Generate new Fusion applications from predefined templates
• Development server with hot reload and service discovery
• Application manifest and configuration management
• Automated building, bundling, and deployment
• Environment-specific configuration handling
• Integrated authentication and authorization
• CI/CD pipeline support with automated publishing
• Plugin system: Extensible architecture with optional plugins (e.g., AI/LLM commands)

Prerequisites

• Node.js (LTS version recommended)
• pnpm (or npm/yarn) package manager
• Fusion Framework app or portal project (or create a new one)
• Access to Fusion services (for authentication and deployment)

Features & Benefits

• 🚀 Unified developer experience: Single tool for the entire development lifecycle - from local development to production deployment
• ⚡ Rapid local development: Built-in dev server with hot reload, service discovery, and real-time feedback
• 🎯 Environment-specific configuration: Seamlessly manage manifests and configs across dev, test, and production environments
• 🔐 Integrated authentication: Secure your apps locally and in CI/CD with Azure AD integration and token management
• 🔍 Service discovery: Built-in support for Fusion services with automatic endpoint resolution
• 📦 Automated bundling & deployment: One-command building, packaging, and publishing to Fusion registry
• 🏗️ Extensible architecture: Support for apps, portals, widgets, and future Fusion components
• 📚 Comprehensive documentation: Migration guides, detailed setup instructions, and troubleshooting resources

Getting Started

Install the CLI

pnpm add -D @equinor/fusion-framework-cli

Create a new Fusion application from template

Generate a new Fusion application using predefined templates:

# Create a new app with interactive template selection
pnpm fusion-framework-cli app create my-new-app

# Create with a specific template
pnpm fusion-framework-cli app create my-app --template react-app

# Create in a specific directory with debug logging
pnpm fusion-framework-cli app create my-app --directory ./projects --debug

Initialize or update your app's manifest and config files

Create the required configuration files for your app:

• app.manifest.ts - Defines your app's metadata and capabilities
• app.config.ts - Contains runtime configuration and environment variables

See Developing Apps for detailed setup and configuration guidance.

Start the development server

pnpm fusion-framework-cli dev

Log in to the Fusion Framework (if needed)

pnpm fusion-framework-cli auth login

Build and publish your app

# Publish without config
pnpm fusion-framework-cli publish --env <environment>

# Publish and upload config in one command
pnpm fusion-framework-cli publish --env <environment> --config

Build or publish snapshot artifacts

[!CAUTION] Snapshot versions are designed for preview and testing purposes only (e.g., pull requests, CI/CD test deployments). The snapshot version only affects the manifest build metadata — your package.json and source files remain unchanged.

• Use --snapshot to emit timestamped snapshot versions
• Default: --snapshot → {version}-snapshot.{unix_timestamp}
• Optional identifier: --snapshot pr-123 → {version}-pr-123.{unix_timestamp}
• Semver coercion strips any pre-release suffix first, e.g. 1.2.3-beta.1 → 1.2.3-snapshot.{unix_timestamp}

Common use cases:

• Pull request previews: --snapshot pr-456
• Nightly builds: --snapshot nightly
• Feature branch testing: --snapshot feature-xyz

# Package an app with a snapshot version
pnpm fusion-framework-cli app pack --snapshot
pnpm fusion-framework-cli app pack --snapshot pr-123

# Publish with a snapshot version
pnpm fusion-framework-cli app publish --snapshot
pnpm fusion-framework-cli app publish --snapshot nightly

Upload configuration

# Upload config with publish command
pnpm fusion-framework-cli publish --config --env <environment>

# Or upload config separately
pnpm fusion-framework-cli app config --publish --env <environment>

Tip: For CI/CD and automation, set the FUSION_TOKEN environment variable. See Authentication for details.

Common Commands

Command	Description
pnpm fusion-framework-cli app create	Create new Fusion applications from templates
pnpm fusion-framework-cli auth ...	Authenticate with Fusion
pnpm fusion-framework-cli app ...	Working with Fusion applications
pnpm fusion-framework-cli portal ...	Working with Fusion portal templates
pnpm fusion-framework-cli disco ...	Service discovery and resolution

Optional Plugins:

Command	Description
pnpm fusion-framework-cli ai ...	AI/LLM commands (requires @equinor/fusion-framework-cli-plugin-ai)

Plugin System:

The CLI supports optional plugins that extend functionality. To use plugins:

• Install the plugin package: pnpm add -D @equinor/fusion-framework-cli-plugin-ai
• Create a fusion-cli.config.ts file in your project root:

  import { defineFusionCli } from '@equinor/fusion-framework-cli';
  
  export default defineFusionCli(() => ({
    plugins: [
      '@equinor/fusion-framework-cli-plugin-ai',
    ],
  }));
  

Plugins are automatically discovered and loaded when the CLI starts. The config file can be .ts, .js, or .json. If no config file exists, the CLI works normally without plugins.

Example: package.json

A minimal example for a Fusion Framework app:

{
  "name": "@equinor/fusion-framework-app",
  "version": "1.0.0",
  "description": "My Fusion Framework Application",
  "main": "dist/bundle.js",
  "files": [
    "dist/",
    "assets/",
    "README.md"
  ],
  "scripts": {
    "build": "fusion-framework-cli app build",
    "dev": "fusion-framework-cli dev",
    "publish": "fusion-framework-cli app publish"
  },
  "devDependencies": {
    "@equinor/fusion-framework-cli": "^11.0.0"
  }
}

Key fields:

• main: Required - Points to your build output directory (CLI uses this to determine where to place built files)
• files: Specifies which files to include in your app bundle
• scripts: Convenient shortcuts for common CLI commands

Note: The CLI determines the build output location from the main field in your package.json. If not specified, it defaults to dist/bundle.js.

Documentation

Getting Started

• Developing Apps: Complete guide to building, configuring, and deploying Fusion applications
• Developing Portals: Guide to building, configuring, and publishing portal templates
• Dev Server: Understanding how the development server works, including architecture and configuration

Setup & Configuration

• Authentication: Setting up authentication for local development and CI/CD environments
• libsecret Installation: Fix credential storage issues on Linux systems

Migration & Updates

• Migration Guide: v10 to v11: Breaking changes, deprecated commands, and upgrade instructions

Additional Resources

• CLI Command Reference: Detailed documentation of all available commands and options
• CI/CD Best Practices: Automated workflows and deployment strategies
• Troubleshooting Guide: Common issues and solutions

Internal Tools (Fusion Core Team Only)

• AI Commands: ⚠️ Internal use only - AI-powered chat, embeddings, and search commands for codebase understanding (not supported for third-party users ...yet)

  Troubleshooting

Common Issues

Authentication & Credentials

• Authentication issues? See Authentication Guide for token setup and troubleshooting
• libsecret errors on Linux? Install libsecret using our installation guide

CLI & Commands

• Command not found? Ensure node_modules/.bin is in your PATH or use pnpm/npx
• Permission errors? Check that you have the correct access rights to Fusion services

Build & Development

• Build errors? Verify your app.manifest.ts and app.config.ts files for syntax errors
• Dev server not starting? Check for port conflicts (default: 3000) or use --port option
• Missing dependencies? Ensure all required packages are installed with pnpm install

Publishing & Deployment

• Upload failures? Verify your app is registered in the Fusion App Admin
• Environment issues? Check that you're using the correct --env parameter

Getting Help

• Detailed troubleshooting: See our comprehensive troubleshooting guide
• Found a bug? Open an issue on our GitHub repository
• Need support? Check the docs folder or reach out to the Fusion team