npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@financial-times/x-engine

v14.6.2

Published

This module is a consolidation library to render x-dash components with any compatible runtime.

Downloads

35,468

Readme

x-engine

This module is a consolidation library to render x-dash components with any compatible runtime.

Installation

This module is supported on Node 12 and is distributed on npm.

npm install -S @financial-times/x-engine

You'll also need to install your chosen runtime and any related dependencies. Some compatible runtimes are:

* Usage of Hyperapp depends on a small modification to higher-order components to accept children as a second argument rather than receiving them appended to props.

Configuration

To start you must specify your runtime configuration within package.json. This instructs x-engine which modules to load for your environment. You may specify different runtimes for server and browser rendering depending on your needs.

This module includes several presets for popular tools and frameworks including React, Preact, and Hyperons. For example to use Hyperons on the server and Preact in the browser you may use the name of their preset:

{
	"x-dash": {
		"engine": {
			"server": "hyperons",
			"browser": "preact"
		}
	}
}

But if your chosen tool does not have a preset then the configuration for it can be provided with the expanded configuration format. The example below shows how to load the VDO module and use its createElement factory function*:

{
	"x-dash": {
		"engine": {
			"server": {
				"runtime": "vdo",
				"factory": "createElement"
			}
		}
	}
}

* A JSX factory function is a variadic function with the signature fn(element, properties, ...children), examples include React.createElement and Preact.h. See the FAQ section for more information.

† Variadic means that the function accepts a variable number of arguments. The ... before the last arguments name is a rest parameter, meaning it will collect "the rest" of the arguments.

Rendering

Server-side

If your chosen runtime factory returns a string then you can pass properties to the component and immediately use the returned value:

const { Teaser } = require('@financial-times/x-teaser');

app.get('/teaser', (request, response) => {
	const properties = { … };
	response.send(Teaser(properties));
});

But if your factory method returns a framework-specific intermediary code then you'll need to load the specified render method to render the node into a string or stream:

const { render } = require('@financial-times/x-engine');
const { Teaser } = require('@financial-times/x-teaser');

app.get('/teaser', (request, response) => {
	const properties = { … };
	const nodes = Teaser(properties);
	response.send(render(nodes));
});

Client-side

To use components on the client-side you will first need to add the x-engine plugin to your Webpack configuration file. Under the hood this uses DefinePlugin to wire up your chosen runtime.

// webpack.config.js
const xEngine = require('@financial-times/x-engine/src/webpack');

module.exports = {
	plugins: [
		xEngine()
	]
};

You can then install and use x- components in your client-side code:

import { h } from '@financial-times/x-engine';
import { Teaser } from '@financial-times/x-teaser';

export default const TeaserList = (props) => (
	<ul class="TeaserList">
		{props.items.map((item) => (
			<li className="TeaserList-Item">
				<Teaser {...item} layout="small" showImage={true} />
			</li>
		))}
	</ul>
);

Client-side through n-ui

In order to configure n-ui to compile x-dash based .jsx files you will also need to add the following to n-ui-build.config.js.

// n-ui-build.config.js
const xEngine = require('@financial-times/x-engine/src/webpack');

module.exports = {
	plugins: [
		xEngine()
	],
	pragma: 'h'
};

You will also need to import the factory function from x-engine in each .jsx file.

import { h } from '@financial-times/x-engine'

FAQ

This sounds complicated… is it a magic black box?

There is no magic. The source code for the server-side integration is less than 60 lines of unexciting code. The Webpack plugin for client-side usage is even smaller.

What is a "factory function"?

A factory function is a variadic function with the signature fn(element, properties, ...children), examples include React.createElement and Preact.h. It may return the framework's representation of a HTML node or a formatted string depending on the runtime you're using.

Which runtime should I use?

Whichever one you want! React, Preact, Rax, and Nerv are all largely compatible with one another. If you don't want the overhead of a framework, or are rendering static HTML, then it's worth investigating the Hyperons or VDO modules.

What about Hyperscript?

Hyperscript currently only supports passing a tag name (a string) as the first argument. This limitation means you cannot currently reference components inside other components.