trucks-compiler
v0.3.6
Published
Web component compiler library
Downloads
12
Readme
Trucks Compiler
Web component compiler and package manager
Compiles web components declared as HTML to separate Javascript, CSS and HTML files.
Install
npm i trucks-compiler --save-dev
Usage
const trucks = require('trucks-compiler');
trucks(
{
files: ['components.html'],
transforms: ['skate'],
out: 'build',
force: true
},
(err, state) => {
if(err) {
throw err;
}
console.log(state);
}
);
Plugins
Plugin Types
Core Plugins
Core plugins are bundled with the trucks-compiler libary and run the main compiler phases:
- load Read the HTML import tree.
- parse Parse the
<dom-module>
elements. - transform Run tree transformations.
- generate Create output file contents.
- write Write output files to disc.
An additional plugin sources reads the entire component tree by combining the load and parse plugins.
The trucks-compiler library exposes constants for each of the core plugins so you can avoid string literals when modifying the plugins list:
const trucks = require('trucks-compiler')
, options = {
files: ['components.html'],
plugins: [trucks.LOAD, trucks.PARSE]
};
Typically you should not need to modify the plugins
list but it can be useful when you need a subset of the core compiler phases to be executed, for example to inspect the component tree without writing any files.
Protocol Plugins
Protocol plugins are initialized by the load phase they are responsible for registering a protocol with a class that will resolve the URL to component files or an alternative compiler configuration. See the http plugin implementation.
Transform Plugins
Transform plugins are executed by the transform phase when the entire component tree is ready. They should perform transformations on the component tree creating output files when needed. See the csp plugin implementation.
Generator Plugins
Generator plugins are executed by the generate phase and may be used to create additional output files or perform extra processing after transformations have been applied. See the page plugin implementation.
Writing Plugins
Plugins are named functions that are passed the compiler state object and a configuration for the plugin and return a closure.
function plugin(state, conf) {
return function(state, cb) {
cb(null, state);
}
}
Closures returned by the plugin functions are executed asynchronously (except protocol plugins which are synchronous) in series and may modify the state object.
Plugin functions may return an array of plugin functions which is useful to group related plugins, see the sources plugin for an example.
Loading Plugins
To load a particular plugin use the corresponding array option:
const options = {
files: ['components.html'],
plugins: [trucks.LOAD]
};
Plugins may be functions (or an object with a plugin
function) but typically are declared as strings.
When plugins are declared as strings and do not resolve to an absolute path they are treated as modules to require using a naming convention.
Core plugins use the trucks-plugin
prefix so in the above example the package trucks-plugin-load
will be loaded.
Protocol plugins use the protocols
array and the trucks-resolver
prefix. For example to load the trucks-resolver-http
plugin:
const options = {
files: ['components.html'],
protocols: ['http']
};
Transform plugins are defined in the transforms
array and use the trucks-transform
prefix. For example to load the trucks-transform-csp
plugin:
const options = {
files: ['components.html'],
transforms: ['csp']
};
Generator plugins are defined in the generators
array and use the trucks-generator
prefix. For example to load the trucks-generator-page
plugin:
const options = {
files: ['components.html'],
generators: ['page']
};
Configuring Plugins
To configure a plugin you can set a configuration object using the plugin id:
const options = {
files: ['components.html'],
plugins: [trucks.LOAD],
conf: {
plugins: {
load: {/* plugin configuration goes here */}
}
}
};
By default the plugin id is the name of the function but it may be changed by assigning an id
:
function plugin(state, conf) {
return function(state, cb) {
cb();
}
}
plugin.id = 'custom-plugin';
module.exports = plugin;
To configure such a plugin use:
const options = {
conf: {
plugins: {
'custom-plugin': {/* plugin configuration goes here */}
}
}
};
Options
This document shows the default options used when none are provided.
const options = {
// array list of component source files
files: null,
// base path for relative paths (default: cwd)
base: undefined,
// output directory
out: undefined,
// name of output files (does not include a file extension)
name: 'components',
// set or override the file path for the HTML output
html: undefined,
// set or override the file path for the CSS output
css: undefined,
// set or override the file path for the Javascript output
js: undefined,
// force overwrite files if they already exist
force: false,
// options to pass to babel
babel: {},
// override the default operating system EOL for file concatenation
eol: undefined,
// array list of configuration files to load and merge
rc: undefined,
// array list of plugins to execute
plugins: undefined,
// array list of transform plugins to run
transforms: undefined,
// array list of protocol resolvers
protocols: undefined,
// map of plugin configuration objects
conf: {
// configuration for compiler plugins
plugins: {},
// configuration for transform plugins
transforms: {},
// configuration for protocol resolvers
protocols: {}
},
before: {
// array list to run before plugins or transforms
plugins: undefined,
transforms: undefined
},
after: {
// array list to run after plugins or transforms
plugins: undefined,
transforms: undefined
},
// map of component identifiers to stylesheets
// used by the `style-extract` and `style-inject` transforms
// non-absolute paths are resolved relative to the output directory
stylesheets: undefined
}
module.exports = options;
API
trucks
trucks(opts, cb)
Compile component files to CSS, Javascript and HTML.
Returns compiler state.
opts
Object processing options.cb
Function callback function.
Options
files
Array list of HTML files to compile.out
String output directory for files.force
Boolean overwrite files that already exist.name
String=components name of the output files.rc
Array|String configuration files to load as options.babel
Object options to pass to babel transform.conf
Object configuration for plugins and transforms.before
Object before hooks for plugins and transforms.after
Object after hooks for plugins and transforms.html
String path to write the generated template markup.css
String path to write the generated stylesheet.js
String path to write the generated javascript.eol
String override the default EOL for concatenation.
CompilerState
Encapsulates the state of the compiler plugin execution.
CompilerState
public CompilerState(options, compiler)
Creates a compiler state.
options
Object computed options.compiler
Function reference to the main compiler entry point.
OutputFile
Represents an output file that will be written to disc when the write plugin is executed.
To get an instance of this class call state.getFile()
.
OutputFile
public OutputFile(file, name, base, options)
Creates an output file.
file
String path to the file.name
String relative path for the file.base
String base path for the file.options
Object computed options.
prepend
prepend(buf)
Prepend data to this output file.
buf
String contents to prepend to the file.
append
append(buf)
Append data to this output file.
buf
String contents to append to the file.
contents
Array contents
list of file contents.
getFileContents
public getFileContents()
Get the computed contents for the output file.
Should be called once just prior to writing the file to disc.
Returns string file contents.
Registry
Registry for a mapping between protocol schemes and resolver classes.
Registry
Create a new scheme registry.
setDefault
public setDefault(val)
Set the default scheme resolver.
val
Function resolver class.
getDefault
public getDefault()
Get the default scheme resolver.
Will be null
if no plugins have registered a default handler by calling
the setDefault
method.
Returns a default resolver class.
getResolver
public getResolver(scheme)
Get the resolver class for a given scheme.
If the scheme is invalid (false) then a default scheme is returned, if no
default scheme has been registered the return value is null
.
If a resolver is not declared for the scheme returns undefined
.
Returns a resolver class for the scheme.
scheme
String protocol scheme.
register
public register(scheme, resolver)
Register a resolver class for a scheme.
Scheme names should include a trailing colon.
scheme
String protocol scheme.resolver
Function constructor function.
factory
public factory(state, href, parent)
Create a new resolver for an href
.
state
Object compiler state.href
String the URL to resolve.parent
Object a parent resolver instance.
ComponentTree < ComponentImport
Represents the root of a component hierarchy.
ComponentFile < ComponentImport
Represents a file in the component tree.
ComponentFile
public ComponentFile(file, contents, parent)
Creates a component file node.
file
String path to the file.contents
String file contents.parent
Object file owner.
ComponentModule < ComponentNode
Represents a module defined by a <dom-module>
element.
ComponentModule
public ComponentModule(id, parent)
Creates a component module node.
id
String module identifier.parent
Object module owner.
ComponentTemplate < ComponentTrait
Represents a template defined by a <template>
or <link>
element.
ComponentStyle < ComponentTrait
Represents a style defined by a <style>
or <link>
element.
ComponentScript < ComponentTrait
Represents a script defined by a <script>
element.
Component < ComponentNode
Represents a component node with a main template, list of template partials and component local styles.
Component
public Component(template, parent)
Creates a component node.
template
Object primary template for the component.parent
Object component owner (module).
#getLevel
static getLevel([lvl])
Get an integer level for a bitwise level integer or a string level.
When a string is given then that level and all levels above it are enabled.
If the given argument is not a valid log level identifier or integer
undefined
is returned.
Returns an integer log level.
lvl
String|Number log level.
Documents
For insights into the compiler phases and data structures see COMPILER.
License
MIT
Created by mkdoc on August 7, 2016