@trackunit/iris-app-sdk-vite

Custom NX executors for building and serving Iris Apps using Vite.

Trackunit Iris App SDK are used by developers to integrate custom functionality into the Trackunit Manager platform.

For more info and a full guide on Iris App SDK Development, please visit our Developer Hub.

Installation

This package is included as part of the Iris App SDK. Run through the getting started guide here: Getting Started

Usage

Serve Executor

Start the Vite dev server for your Iris App:

nx run your-app:serve

Add to your project.json:

{
  "targets": {
    "serve": {
      "executor": "@trackunit/iris-app-sdk-vite:serve",
      "options": {}
    }
  }
}

Build Executor

Build your Iris App for production:

nx run your-app:build

Add to your project.json:

{
  "targets": {
    "build": {
      "executor": "@trackunit/iris-app-sdk-vite:build",
      "options": {
        "outputPath": "dist/apps/your-app"
      },
      "outputs": ["{options.outputPath}"]
    }
  }
}

Configuration Options

Serve Options

| Option | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------------------------- | | port | number | No | Dev server port (default: auto-select from 22220-22229) | | host | string | No | Dev server host (default: "localhost") | | viteConfig | string | No | Path to optional custom vite config file for overrides |

Build Options

| Option | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------------------------ | | outputPath | string | Yes | Output directory for the build | | viteConfig | string | No | Path to optional custom vite config file for overrides |

Custom Vite Configuration

By default, no vite.config.ts file is required - the executor automatically handles everything based on your iris-app-manifest.ts.

If you need to customize the Vite config, create a vite.config.ts file in your app directory:

import type { UserConfig } from "vite";

export default async (defaultConfig: UserConfig): Promise<UserConfig> => {
  return {
    ...defaultConfig,
    // Your customizations here
    // Example: Add custom plugins
    plugins: [...(defaultConfig.plugins ?? []), myCustomPlugin()],
  };
};

Then reference it in your project.json:

{
  "targets": {
    "build": {
      "executor": "@trackunit/iris-app-sdk-vite:build",
      "options": {
        "outputPath": "dist/apps/your-app",
        "viteConfig": "apps/your-app/vite.config.ts"
      }
    },
    "serve": {
      "executor": "@trackunit/iris-app-sdk-vite:serve",
      "options": {
        "viteConfig": "apps/your-app/vite.config.ts"
      }
    }
  }
}

Note: Your custom config function receives the default config with all Iris App plugins already applied. You should spread the default config to preserve the required functionality.

Migration from @nx/vite

If you were using @nx/vite executors directly, update your project.json to use these executors instead:

Before:

{
  "targets": {
    "build": {
      "executor": "@nx/vite:build",
      "options": {
        "outputPath": "dist/apps/your-app"
      }
    },
    "serve": {
      "executor": "@nx/vite:dev-server",
      "options": {}
    }
  }
}

After:

{
  "targets": {
    "build": {
      "executor": "@trackunit/iris-app-sdk-vite:build",
      "options": {
        "outputPath": "dist/apps/your-app"
      }
    },
    "serve": {
      "executor": "@trackunit/iris-app-sdk-vite:serve",
      "options": {}
    }
  }
}

Key Differences

These executors solve the tsconfig paths resolution problem that occurs when using Vite directly:

1. Automatic tsconfig paths registration - Registers tsconfig paths before loading any modules
2. Automatic manifest loading - Loads your iris-app-manifest.ts automatically
3. Pre-configured plugins - Applies all required Iris App Vite plugins automatically
4. No config file required - The executor handles everything based on your manifest

Debugging

Verbose Mode

Run with the --verbose flag to see detailed configuration information:

nx run your-app:serve --verbose
nx run your-app:build --verbose

This will output the Vite plugins configuration being used.

React DevTools

Run a global install of react-devtools.

With volta:

volta install react-devtools

Run react-devtools from the terminal to launch the standalone DevTools app:

react-devtools

React-devtools will automatically connect to whichever Iris App is running in your browser.

Common Issues

"Failed to resolve dependency" warnings

These warnings during development are typically harmless and occur during Vite's dependency pre-bundling. If your app loads correctly, they can be ignored.

Trackunit

This package was developed by Trackunit ApS. Trackunit is the leading SaaS-based IoT solution for the construction industry, offering an ecosystem of hardware, fleet management software & telematics.