Skip to content

TypeScript Build Tools ​

This guide documents the build tools and processes used in the Phenix Design System to compile TypeScript files into optimized JavaScript.

Overview ​

The Phenix Design System uses a streamlined build process to convert TypeScript source files into production-ready JavaScript. The process includes:

  • TypeScript compilation with type checking
  • Module bundling with dependency resolution
  • Source map generation for debugging
  • UMD module format output for broad compatibility
  • Production optimization

Build Environment ​

Node.js and NPM ​

The build process requires:

  • Node.js: v14.0.0 or higher
  • NPM: v6.0.0 or higher

Primary Build Tools ​

ToolPurpose
WebpackModule bundling and asset management
ts-loaderTypeScript compilation
concurrentlyRun multiple build processes simultaneously

Webpack Configuration ​

The TypeScript build process uses a dedicated webpack configuration file (typescript.webpack.js), which defines how TypeScript files are processed:

javascript
/*jslint es6 */
const path = require('path');

module.exports = {
    mode: "production",
    entry: path.join(__dirname, '/src/scripts/index.ts'),
    devtool: "source-map",
    output: {
        filename: 'js/phenix.js',
        path: path.join(__dirname, '/assets/'),
        globalObject: 'this',
        library: {
            type: 'umd',
            name: 'Phenix',
        }
    },
    module: {
        rules: [
            {
                test: /\.tsx?$/,
                loader: 'ts-loader',
                exclude: /node_modules/,
            }
        ]
    },
    resolve: {
        extensions: [".ts", ".js"]
    },
};

Key features of this configuration:

  1. Entry Point: The main file src/scripts/index.ts serves as the starting point
  2. Source Maps: Enabled with the devtool option for debugging
  3. Output Format: UMD (Universal Module Definition) for maximum compatibility
  4. Global Object: Library exposed as Phenix in browser environments
  5. TypeScript Processing: All .ts and .tsx files processed through ts-loader

TypeScript Configuration ​

The TypeScript compiler options are defined in tsconfig.json:

json
{
    "compilerOptions": {
        "strict": false,
        "forceConsistentCasingInFileNames": true,
        "module": "commonjs",
        "target": "es2017",
        "sourceMap": true,
        "esModuleInterop": true,
    }
}

This configuration:

  • Sets ES2017 as the JavaScript target version
  • Uses CommonJS for module format
  • Generates source maps for debugging
  • Enables compatibility between CommonJS and ES modules
  • Disables strict type checking for flexibility

Build Scripts ​

The build process is controlled through NPM scripts defined in package.json:

json
"scripts": {
    "phenix-start": "concurrently --kill-others \"npm run phenix-sass\" \"npm run phenix-ts\" \"npm run phenix-blocks\"",
    "phenix-ts": "npx webpack --config typescript.webpack.js --watch",
    "phenix-sass": "npx node-sass --watch src/sass -o assets/css --output-style compressed --source-map true",
    "phenix-blocks": "wp-scripts start"
}

The phenix-ts script:

  • Runs webpack using the TypeScript configuration
  • Enables watch mode for automatic recompilation during development
  • Outputs compiled JavaScript to the assets directory

Build Process Flow ​

When you run the TypeScript build process, the following sequence occurs:

  1. Entry Point Resolution: Webpack starts with src/scripts/index.ts
  2. Dependency Graph Creation: Webpack analyzes imports to build a module dependency graph
  3. TypeScript Compilation: ts-loader transpiles TypeScript to JavaScript
  4. Module Bundling: Webpack combines all modules into a single output file
  5. UMD Wrapping: Code is wrapped in UMD format for cross-platform compatibility
  6. Source Map Generation: Source maps are created for debugging
  7. Output Generation: Compiled bundle is written to assets/js/phenix.js

Output Files ​

The build process generates two primary files:

  • assets/js/phenix.js - The compiled JavaScript bundle
  • assets/js/phenix.js.map - Source map for development debugging

Development Workflow ​

Starting the Development Environment ​

To start the complete development environment with file watching:

bash
npm run phenix-start

This runs all build processes in parallel:

  • TypeScript compilation (with auto-recompilation)
  • SASS compilation (with auto-recompilation)
  • WordPress block development

TypeScript-Only Development ​

If you only need to work on TypeScript files:

bash
npm run phenix-ts

Extending the Framework ​

Custom Component Development ​

To create your own components or extensions to the framework:

  1. Create a component file in the appropriate directory:
typescript
// src/scripts/components/custom-component.ts

/**
 * Custom Component Implementation
 * @param {Object} options - Configuration options
 * @returns {PhenixElements} - Returns this for chaining
 */
Phenix.prototype.customComponent = function(options = {}) {
    return this.forEach((element) => {
        // Component implementation logic
    });
};
  1. Import your component in index.ts or a custom entry file:
typescript
// Add to the index.ts imports
import './components/custom-component';
  1. Run the build process to incorporate your component

Creating a Custom Build ​

For specialized builds with a subset of components:

  1. Create a custom entry file:
typescript
// src/scripts/custom-build.ts
import './index'; // Import core functionality

// Only import needed components
import './components/dropdown';
import './components/tabs';

// Add custom code
Phenix.prototype.customFeature = function() {
    // Implementation
};
  1. Update the webpack entry point:
javascript
// In typescript.webpack.js
entry: path.join(__dirname, '/src/scripts/custom-build.ts'),
  1. Run the build process:
bash
npx webpack --config typescript.webpack.js

Troubleshooting ​

Common Issues ​

  1. Type Errors

    • Problem: TS2339: Property does not exist on type
    • Solution: Verify property names or adjust TypeScript configuration
  2. Module Resolution

    • Problem: Cannot find module
    • Solution: Check import paths and file existence
  3. Webpack Configuration

    • Problem: Configuration file not found
    • Solution: Ensure you're in the correct directory

Best Practices ​

  1. Use TypeScript Features: Embrace type annotations for better code quality
  2. Module Organization: Follow the existing directory structure
  3. Documentation: Add JSDoc comments to your components and methods
  4. Progressive Enhancement: Ensure basic functionality works without JavaScript
  5. Testing: Test components across different browsers

Released under the MIT License.