API

Phenome is designed to be used in Node.js evironment. Phenome compiler API is a single compilation function that accepts object with parameters and returns Promise:

const phenome = require('phenome');

phenome(params)
  .then(() => {
    // compiled succesfully
  })
  .catch((error) => {
    // error happened
  });

Parameters

Parameter Type Default Description
paths string
array

Files to process. It accepts string with Glob pattern or array with such strings where to look for files. For example ./src/*.jsx` to compile all .jsx files in src/ folder

env object

Object with environment variables that will be replaced during compilation

For example, if you specify such env variables:

{
NODE_ENV: 'production'
FOO: true
}

Then you will be able to use them in code like:

if (process.env.NODE_ENV === 'production') {
// do something
}
if (process.env.FOO === true) {
// do something
}

After env variables replacements you may have "constant conditions", check how they work in Phenome components.

In addition to any env variables you pass, there will also be process.env.COMPILER variable passed automatically that will be equal to 'vue' or 'react' depending on target compiler.

replace object

Object with variables that need to be replaced in code. Each key can also be a regular expression, e.g.

{
// replace foo with bar
'foo': 'bar',

// regexp replace
/[a-z]*/: 'foo'
}

After such replacements you may have "constant conditions", check how they work in Phenome components.

react object Object with React compiler parameters. If not specified, then it will not compile React components.
react.out string Path where to save compiled React components
react.env object Same as global env, but specific for React compiler
react.env object Same as global replace, but specific for React compiler
react.helpers object

Object with React component helpers/polyfils that needs to be added to compiled components. By default it is object with the following properties. Each property can be true (force helper to be included), false (force helper not to be included) or auto (by default - auto detect):

Changing these helpers properties can be harmful if you are not 100% sure what they do. It is highly recommended to leave them in auto mode

  • slots - adds ability to use slots for content distribution
  • props - adds specified props to compiled component
  • refs - adds refs support in compiled component. React already support refs, but this helper will automatically convert string refs to callback refs
  • dispatchEvent - adds component method to trigger custom events
  • watch - adds watchers support to component
react.typeScriptDefinitions boolean false

Will generate TypeScript definitions for components when enabled

vue object Object with Vue compiler parameters. If not specified, then it will not compile Vue components
vue.env object Same as global env, but specific for Vue compiler
vue.env object Same as global replace, but specific for Vue compiler
vue.out string Path where to save compiled Vue components
vue.helpers object

Object with Vue component helpers/polyfils that needs to be added to compiled components. By default it is object with the following properties. Each property can be true (force helper to be included), false (force helper not to be included) or auto (by default - auto detect):

Changing these helpers properties can be harmful if you are not 100% sure what they do. It is highly recommended to leave them in auto mode

  • slots - this helper will automatically convert this.slots to Vue's native this.$slots
  • props - adds this.props component getter to return component props
  • refs - this helper will automatically convert this.refs to Vue's native this.$refs
  • dispatchEvent - adds component method to trigger custom events, basically will reuse Vue's native $emit
  • state - adds Phenome-like component state support
  • setState - adds component's method to work with state in Phenome-way

For example, we have the following project structure:

dist/
    react/
    vue/
node_modules
src/
    component-a.jsx
    component-b.jsx
compile.js
package.json

We need to compile Phenome components from src/ folder.

compile.js:

const phenome = require('phenome');

phenome({
  // Path to phenome components
  paths: './src/*.jsx',
  react: {
    // where to save compiled React components
    out: './dist/react/',
  },
  vue: {
    // where to save compiled Vue components
    out: './dist/vue/',
  },
}).then(() => {
  console.log('Compiled succesfully');
}).catch(() => {
  console.log('Oops, error occured');
})

Run in terminal:

$ node ./compile.js

The resulting output will be:

dist/
    react/
        component-a.js
        component-b.js
    vue/
        component-a.js
        component-b.js
node_modules
src/
    component-a.jsx
    component-b.jsx
compile.js
package.json

Configuration File

It is also possible to specify Phenome compiler parameters in configuration file.

We need to create phenome.config.js file in the root of our project and export parameters from this file.

dist/
    react/
    vue/
node_modules
src/
    component-a.jsx
    component-b.jsx
compile.js
phenome.config.js
package.json

phenome.config.js:

module.exports = {
  paths: './src/*.jsx',
  react: {
    out: './dist/react/',
  },
  vue: {
    out: './dist/vue/',
  },
};

compile.js:

const phenome = require('phenome');

// it will automaticall read parameters from config file
phenome().then(() => {
  console.log('Compiled succesfully');
}).catch(() => {
  console.log('Oops, error occured');
})

Transpiling And Bundling

Phenome compiler doesn't do any transpilation (ES-next to ES5) and bundling (don't process imports) - it leaves everything as is. If you need transpilation or bundling, you can just post process compiled React and Vue components with your favorite tools, e.g. Buble, Babel, Rollup, Webpack, etc.

Dependencies

Phenome compiler will compile and process only files that match to Phenome component pattern - default not named object export with at least name and render properties.

If you use any custom dependencies in Phenome components, e.g.:

/* my-component.jsx */
import Utils from './utils/utils.js';

export default {
  // ...
}

make sure your paths pattern covers them. Compiler will not process them but it will copy them to output folder with paths respected.