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
Tool | Purpose |
---|---|
Webpack | Module bundling and asset management |
ts-loader | TypeScript compilation |
concurrently | Run 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:
/*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:
- Entry Point: The main file
src/scripts/index.ts
serves as the starting point - Source Maps: Enabled with the
devtool
option for debugging - Output Format: UMD (Universal Module Definition) for maximum compatibility
- Global Object: Library exposed as
Phenix
in browser environments - TypeScript Processing: All
.ts
and.tsx
files processed through ts-loader
TypeScript Configuration
The TypeScript compiler options are defined in tsconfig.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
:
"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:
- Entry Point Resolution: Webpack starts with
src/scripts/index.ts
- Dependency Graph Creation: Webpack analyzes imports to build a module dependency graph
- TypeScript Compilation: ts-loader transpiles TypeScript to JavaScript
- Module Bundling: Webpack combines all modules into a single output file
- UMD Wrapping: Code is wrapped in UMD format for cross-platform compatibility
- Source Map Generation: Source maps are created for debugging
- 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 bundleassets/js/phenix.js.map
- Source map for development debugging
Development Workflow
Starting the Development Environment
To start the complete development environment with file watching:
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:
npm run phenix-ts
Extending the Framework
Custom Component Development
To create your own components or extensions to the framework:
- Create a component file in the appropriate directory:
// 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
});
};
- Import your component in
index.ts
or a custom entry file:
// Add to the index.ts imports
import './components/custom-component';
- Run the build process to incorporate your component
Creating a Custom Build
For specialized builds with a subset of components:
- Create a custom entry file:
// 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
};
- Update the webpack entry point:
// In typescript.webpack.js
entry: path.join(__dirname, '/src/scripts/custom-build.ts'),
- Run the build process:
npx webpack --config typescript.webpack.js
Troubleshooting
Common Issues
Type Errors
- Problem:
TS2339: Property does not exist on type
- Solution: Verify property names or adjust TypeScript configuration
- Problem:
Module Resolution
- Problem:
Cannot find module
- Solution: Check import paths and file existence
- Problem:
Webpack Configuration
- Problem:
Configuration file not found
- Solution: Ensure you're in the correct directory
- Problem:
Best Practices
- Use TypeScript Features: Embrace type annotations for better code quality
- Module Organization: Follow the existing directory structure
- Documentation: Add JSDoc comments to your components and methods
- Progressive Enhancement: Ensure basic functionality works without JavaScript
- Testing: Test components across different browsers