npm package: @m-filescorporation/create-mfiles-uixv2
Description: CLI tool to create M-Files UIXv2 applications
Author: M-Files
Latest version: 0.0.7

# 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:

```bash
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:**
```bash
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:**
```bash
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):**
```bash
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):
   ```bash
   npm install
   ```
2. **Build the application:**
   ```bash
   npm run build
   ```
3. **Create installation package:**
   ```bash
   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:

```powershell
./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

```powershell
# 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](https://developer.m-files.com/)
- [User Interface Extensibility Framework](https://developer.m-files.com/Frameworks/User-Interface-Extensibility-Framework/)