@dizmo/build

A modern, Vite-based build system for dizmos (dizmo applications). This package is designed to be installed as a dev dependency in dizmos, allowing easy updates via npm update.

Setup

This package is included automatically when you:

• Create a new dizmo: npx @dizmo/create my-dizmo
• Migrate an existing dizmo: npx @dizmo/build migrate (see Migration below)

Usage

These commands are run inside your dizmo project directory that uses this build system.

Build Commands

# Build with defaults (minify ON, sourcemaps ON)
npm run build

# Development build (no minification)
npm run build -- --no-minify

# Production build without sourcemaps
npm run build -- --no-sourcemaps

# Build with obfuscation
npm run build -- --obfuscate

# Clean build artifacts
npm run clean

# Migrate from yeoman-generator-dizmo
npx dizmo-build migrate              # Migrate, keep old files
npx dizmo-build migrate --delete     # Migrate and delete old files
npx dizmo-build migrate --dry-run    # Preview changes

CLI Flags

Build Flags

| Flag | Default | Description | |------|---------|-------------| | --minify | true | Minify output using esbuild | | --no-minify | - | Disable minification (dev mode) | | --sourcemaps | true | Generate source maps | | --no-sourcemaps | - | Disable source maps | | --obfuscate | false | Obfuscate code using javascript-obfuscator | | --no-obfuscate | - | Explicitly disable obfuscation |

Migrate Flags

| Flag | Default | Description | |------|---------|-------------| | --dry-run | false | Preview changes without modifying files | | --delete | false | Delete old build files (gulpfile.js, webpack.config.js, gulp/, etc.) | | --local <path> | - | Use local file: path for @dizmo/build (for development) |

Build Process

The build follows this sequence:

1. TypeScript Check - If tsconfig.json exists, runs tsc --noEmit to catch type errors
2. Clean - Removes existing build/ directory
3. Vite Build - Bundles source code with Vite
4. Obfuscate - If --obfuscate is enabled, applies javascript-obfuscator
5. Post-process HTML - Moves index.html from source/ to root, fixes asset paths
6. Copy Assets - Copies icons to root, other assets to assets/ directory
7. Generate Info.plist - Creates plist from package.json dizmo settings
8. Create Archive - Packages everything into .dzm file (ZIP format)

Build Configuration

• Target: es2022 - Enables modern JavaScript features (class fields, top-level await, etc.)
• SCSS: Uses modern Sass API via bundled sass package
• Warnings: Suppresses expected warnings about dizmoWeb runtime files (dizmojs-*.js, dizmoelements-*.css) that are provided at runtime

Output Structure

build/
├── {name}/                    # Uncompressed dizmo folder
│   ├── index.html             # Entry HTML (at root)
│   ├── index.js               # Bundled JavaScript (at root)
│   ├── index.js.map           # Source map (if enabled)
│   ├── Info.plist             # Dizmo metadata
│   ├── Icon.svg               # Light theme icon
│   ├── Icon-dark.svg          # Dark theme icon
│   ├── Preview.png            # Preview image (if exists)
│   ├── styles/
│   │   └── styles.css         # Compiled stylesheet
│   └── assets/
│       └── ...                # Other assets (not icons/preview)
└── {name}-{version}.dzm       # Final packaged dizmo

Source Project Structure

Expected structure for a dizmo project using this build system:

my-dizmo/
├── package.json               # Must include dizmo.settings section
├── tsconfig.json              # Optional - enables TypeScript checking
├── source/
│   ├── index.html             # Entry HTML
│   ├── index.ts (or .js)      # Entry script
│   └── styles/
│       └── styles.css         # Stylesheets
└── assets/
    ├── Icon.svg               # Required - light theme icon
    ├── Icon-dark.svg          # Required - dark theme icon
    ├── Preview.png            # Optional - preview image
    └── ...                    # Other assets

Troubleshooting

TypeScript errors not caught

The build only runs tsc --noEmit if a tsconfig.json file exists in the project root. Ensure your TypeScript configuration is correct.

Assets not copied

Assets must be in the assets/ directory. Icon.svg, Icon-dark.svg, and Preview.png are copied to the root; all other files go to assets/ in the output.

Migration from yeoman-generator-dizmo

Automated Migration

Use the built-in migration command to automatically update your project:

# Preview changes (dry run)
npx dizmo-build migrate --dry-run

# Run migration
npx dizmo-build migrate

# Run migration and delete old build files
npx dizmo-build migrate --delete

The migration tool will:

1. Update package.json - Set type: module, replace scripts with dizmo-build, remove old dependencies (gulp, webpack, babel, etc.), add @dizmo/build
2. Update index.html - Change <script src="index.js"> to <script type="module" src="./index.ts"> (required for Vite)
3. Add style import - Add the required style import to your entry file (index.ts/index.js)
4. Handle old files - List or delete old build files (gulpfile.js, webpack.config.js, gulp/, etc.)

After Migration

1. Review changes - Check package.json and source files
2. Install dependencies: npm install
3. Build: npm run build
4. Test in dizmoWeb

Testing Migration Locally

To test migration changes during development of @dizmo/build:

1. Clone or copy an old yeoman-generator-dizmo project to the repository root
2. Run migration with the --local flag pointing to the local build:

cd old-dizmo
node ../dizmo-build/dist/bin/dizmo-build.js migrate --local ../dizmo-build
npm install
npm run build

Key Differences

| Old (Gulp/Webpack) | New (Vite) | |-------------------|------------| | ~40+ devDependencies | ~3-4 devDependencies | | gulpfile.js, webpack.config.js | No config files needed | | gulp/, multiple task directories | Single dizmo-build command | | Babel transpilation | esbuild (es2022 target) | | Complex task orchestration | Simple sequential build |

Advanced Configuration (dizmo.config.js)

For advanced use cases, you can create a dizmo.config.js file in your project root to override or extend the default Vite configuration.

Basic Structure

// dizmo.config.js
export default {
  vite: {
    // Vite configuration overrides
  }
};

What Can Be Configured

The vite object accepts any valid Vite configuration options. Common use cases include:

Resolve Aliases

export default {
  vite: {
    resolve: {
      alias: {
        '@': '/source',
        '@components': '/source/components',
        '@utils': '/source/utils'
      }
    }
  }
};

Custom Define Values

export default {
  vite: {
    define: {
      __APP_VERSION__: JSON.stringify('1.0.0'),
      __BUILD_DATE__: JSON.stringify(new Date().toISOString())
    }
  }
};

Additional Plugins

import someVitePlugin from 'some-vite-plugin';

export default {
  vite: {
    plugins: [
      someVitePlugin()
    ]
  }
};

CSS Options

export default {
  vite: {
    css: {
      preprocessorOptions: {
        scss: {
          additionalData: `@import "./source/styles/variables.scss";`
        }
      }
    }
  }
};

Optimizations

export default {
  vite: {
    optimizeDeps: {
      include: ['some-large-dependency']
    },
    build: {
      target: 'es2020'
    }
  }
};

What Cannot Be Overridden

The following settings are managed by @dizmo/build and cannot be overridden:

• build.outDir - Output directory (always build/{name})
• build.rollupOptions.input - Entry point (always source/index.html)
• build.rollupOptions.output.entryFileNames - JS output name (always index.js)
• build.rollupOptions.output.assetFileNames - CSS goes to styles/styles.css
• base - Base path (always ./)

These restrictions ensure the output structure remains compatible with dizmoWeb.

Requirements

• Node.js >= 22.0.0
• npm or compatible package manager

License

ISC