create-mfiles-uixv2

A CLI tool to quickly scaffold M-Files UIXv2 applications with best practices, templates, and build scripts.

Features

• Interactive and non-interactive ("--yes") project creation.
• Choose from multiple templates and languages (JavaScript/TypeScript).
• Supports project creation in a new directory or the current directory (using ".").
• Auto-generates GUIDs and all required config files.
• Validates all input and provides clear error messages.
• Runs npm install automatically after project creation.

Installation & Usage

You can use the CLI directly with npx (recommended) or install globally:

npx @m-filescorporation/create-mfiles-uixv2
# or
npm install -g @m-filescorporation/create-mfiles-uixv2
create-mfiles-uixv2

CLI Options

Usage: create-mfiles-uixv2 [options]

Options:
  -h, --help             Show help information and exit.
  -v, --version          Show version number and exit.
  -l, --language         Specify language (js, ts). Required in --yes mode.
  -t, --template         Specify template (see below for list). Defaults to 'minimal' in --yes mode.
  -p, --project          Project directory name. Use '.' to use the current directory. Required in --yes mode.
  --app-name             Application display name. Defaults to 'My UIXv2 App' in --yes mode.
  --publisher            Publisher name. Defaults to 'Your Company' in --yes mode.
  --description          Application description. Defaults to 'A custom UIXv2 application' in --yes mode.
  -y, --yes              Skip all prompts and use defaults for optional fields.

Interactive Mode (Default)

If you do not use --yes, the CLI will prompt you for any missing information:

• Language selection (JavaScript/TypeScript)
• Template selection (filtered by language)
• Project name (directory to create, or "." for current directory)
• Application name
• Publisher name
• Description

Example:

npx @m-filescorporation/create-mfiles-uixv2

Non-Interactive Mode (--yes)

If you use --yes, you must provide all required options via CLI flags. The CLI will use defaults for optional fields and will not prompt for anything.

• --project (or -p): Required. Name of the directory to create, or . for current directory.
• --language (or -l): Required. js or ts.
• --template (or -t): Optional. Defaults to minimal.
• --app-name, --publisher, --description: Optional. Defaults will be used if not provided.

Example:

npx @m-filescorporation/create-mfiles-uixv2 --project my-app --language js --yes

This will create a new directory my-app with the minimal JavaScript template and default metadata.

Example (current directory):

npx @m-filescorporation/create-mfiles-uixv2 --project . --language ts --template hello-world --yes

This will create a TypeScript "hello-world" project in the current directory (which must be empty).

If any required option is missing, the CLI will throw a clear error and exit.

Template & Language Selection

• You will always select a language first (JavaScript or TypeScript).
• The list of available templates is filtered by language.
• Templates:
  • minimal - Bare minimum template for custom development
  • hello-world - Basic example showing simple UIX functionality
  • command-sample - Example of implementing custom commands
  • built-in-commands-sample - Example of handling built-in M-Files commands
  • show-new-object-window - Template for object creation functionality
  • popup-dashboard - Basic dashboard implementation
  • popup-dashboard-accent-color - Styled dashboard example with accent color
  • shellframe-dashboard - Integrated dashboard implementation
  • assign-to-me - Assignment workflow example

Some templates may only be available for certain languages.

Project Directory Handling

• If you provide a project name (e.g. my-app), a new directory will be created.
• If you provide . as the project name, the project will be created in the current directory (which must be empty).
• The CLI will throw an error if the target directory is not empty or already exists.

Project Structure

The generated project will have a structure similar to:

my-uixv2-app/
├── src/                      # Application source code (template-specific)
│   ├── main.js / main.ts     # Main ShellUI module (always present)
│   ├── dashboard.js/.ts      # Dashboard logic (if template includes dashboard)
│   ├── main.html             # Dashboard HTML (if template includes dashboard)
│   └── style.css             # Dashboard styles (if template includes dashboard)
├── public/                   # Static resources
│   └── __TemplateIcon.ico    # Application icon
├── appdef.xml                # Application definition file (generated)
├── package.json              # Project metadata and dependencies
├── install-application.ps1   # PowerShell script for installing the application
└── README.md                 # Project documentation

After Project Creation

1. Install dependencies (done automatically):

   npm install

2. Build the application:

   npm run build

3. Create installation package:

   npm run bundle

Installing the Application

After building and bundling your project, you can install it into an M-Files vault using the provided PowerShell script:

./install-application.ps1

This script will:

• Use the configuration in install-application.user.json to determine which vault(s) and server to target.
• Install the latest .mfappx package from the dist directory.
• Support additional parameters for advanced scenarios (see below).

install-application.user.json

This file contains user-specific installation settings, such as:

• Vault connection details (vault name, network address)
• Installation groups (e.g., ["default"])
• Other options for customizing the install process

You can edit this file to match your M-Files environment before running the install script.

Example PowerShell Usage

# Basic installation (uses install-application.user.json)
./install-application.ps1

# Install to a specific vault
./install-application.ps1 -vaultName "Example Vault"

# Force application reload in M-Files Desktop
./install-application.ps1 -forceRelogin

# Show help and all available options
./install-application.ps1 -help

Note:

• The -forceRelogin parameter is only needed when developing/testing with M-Files Desktop. It forces the desktop client to reload the application by logging out and back in. This will close all open documents and cards in the desktop client. Web clients do not require this as they handle application updates differently.

Error Handling & Validation

• The CLI validates all required options and will throw clear errors if anything is missing or invalid.
• In --yes mode, no prompts are shown. If a required option is missing, the CLI will exit with an error.
• The CLI will not overwrite existing or non-empty directories.

More Information

• M-Files Developer Portal
• User Interface Extensibility Framework