API design principles for Rspack, focusing on webpack compatibility, versioning, and maintainability.
Prioritize compatibility with webpack's API for seamless migration.
Compatibility Levels:
- Full: Works identically to webpack
- Partial: Works with differences/limitations
- Not Compatible: Not supported (documented with alternatives)
Goals:
- API compatibility: Match webpack's public API
- Plugin compatibility: Support webpack plugins (when possible)
- Loader compatibility: Support webpack loaders
- Configuration compatibility: Accept webpack config format
When compatibility conflicts with performance, prioritize performance but provide alternatives.
Examples:
- Native Rust implementations over JavaScript
- Optimized algorithms over exact webpack behavior
- Parallel processing over sequential execution
APIs should be type-safe with good TypeScript support.
Guidelines:
- Use TypeScript for all public APIs
- Provide comprehensive type definitions
- Use discriminated unions for options
- Avoid
anytypes in public APIs
APIs should be intuitive, well-documented, and provide helpful error messages.
Guidelines:
- Clear, descriptive names
- Comprehensive documentation with examples
- Helpful error messages with suggestions
- Good IDE support (autocomplete, type hints)
interface RspackOptions {
entry?: EntryNormalized;
output?: OutputNormalized;
module?: ModuleOptions;
plugins?: RspackPluginInstance[];
}Principles:
- Optional properties for all configuration
- Sensible defaults
- Nested objects for related options
- Support both object and array formats
interface Plugin {
apply(compiler: Compiler): void;
name?: string;
}Principles:
- Simple, single-method interface
- Optional name for identification
- Access through hooks
- Support both class and function plugins
function loader(
this: LoaderContext,
content: string | Buffer,
sourceMap?: SourceMap,
): string | Buffer | void;Principles:
- Simple function signature
- Context via
this - Support async loaders
- Chainable (output → next loader input)
compiler.hooks.done.tap('PluginName', (stats) => {
// Handle completion
});Principles:
- Consistent naming (camelCase)
- Clear hook names
- Type-safe signatures
- Support sync and async hooks
Follow Semantic Versioning:
- MAJOR: Breaking changes
- MINOR: New features (backward compatible)
- PATCH: Bug fixes (backward compatible)
Only in major versions, carefully planned.
Types:
- Removing/renaming public APIs
- Changing function signatures
- Changing default behavior
- Removing configuration options
Migration Path:
- Deprecation warnings before removal
- Migration guides for major versions
- Compatibility layers when possible
Process:
- Mark with
@deprecatedtag - Add deprecation notice in docs
- Log deprecation warning at runtime
- Remove in next major version
Timeline:
- At least one minor version with warning
- Removal in next major version
- Migration guide provided
- Old formats continue to work
- New options are additive (optional)
- Deprecated options show warnings but work
- Migration tools for major changes
Levels:
- Full: Works without modification
- Compatibility Layer: Works with adapter
- Not Compatible: Needs rewrite (documented)
Checks:
- Test against popular webpack plugins
- Document compatibility status
- Provide alternatives for incompatible plugins
Breaking Changes:
- Changing return types
- Removing methods
- Changing method signatures
- Changing behavior
Non-Breaking Changes:
- Adding new methods
- Adding optional parameters
- Adding new configuration options
- Performance improvements
- Build Errors: Module build failures, resolution errors, compilation errors
- Configuration Errors: Invalid config, missing options, type mismatches
- Runtime Errors: Plugin errors, loader errors, file system errors
Guidelines:
- Clear, actionable messages
- Include context (file path, line number)
- Provide suggestions for fixes
- Link to documentation when relevant
- Export types from main entry point
- Use interfaces for object shapes
- Use type aliases for unions/intersections
- Document complex types
- Use
@internaltag for internal APIs - Don't export implementation details
- Use
export typefor type-only exports
Required:
- Description of what API does
- Parameter descriptions with types
- Return value description
- Usage examples
- Related APIs
Required:
- Description of option
- Default value
- Type information
- Example usage
- Related options
- All public APIs should have tests
- Test success and error cases
- Test edge cases and boundaries
- Test compatibility with webpack
- Test against webpack test suite (where applicable)
- Test popular plugins and loaders
- Test migration scenarios
- Document compatibility status
- Minimize overhead in hot paths
- Use efficient data structures
- Avoid unnecessary allocations
- Profile API calls
- Batch operations when possible
- Lazy evaluation for expensive operations
- Caching for repeated operations
- Parallel processing where applicable
Plugins can:
- Access compilation state
- Modify compilation process
- Add new assets
- Transform existing assets
- Hook into any compilation stage
Loaders can:
- Transform source code
- Access loader context
- Emit additional files
- Handle errors gracefully
When adding hooks:
- Follow existing naming conventions
- Document hook purpose and timing
- Provide type-safe signatures
- Consider performance implications
- Install Rspack
- Update configuration (minimal changes)
- Test build
- Address compatibility issues
- Optimize for Rspack-specific features
Common Issues:
- Plugin compatibility
- Loader compatibility
- Configuration differences
- Behavior differences
- Read migration guide
- Update dependencies
- Update configuration (if needed)
- Update code (if breaking changes)
- Test thoroughly
- Use TypeScript for type safety
- Read documentation before using APIs
- Handle errors appropriately
- Follow migration guides for upgrades
- Design for extensibility
- Consider performance implications
- Provide clear error messages
- Document thoroughly
- Maintain backward compatibility