@xwp/block-helpers v0.0.2

XWP Block Helpers

This package serves as JavaScript library, which can be installed via NPM, to provide a set of tools to help speed up the development of Gutenberg Blocks.

Installation

npm i -D @xwp/block-helpers

Usage

This library provides three types of helpers: components (ie. React components), hooks (ie. React hooks) and utils. Each of these helpers can be imported as a subpackage as to keep the import footprint smaller. Treeshaking is also active in this library, meaning that unused exports will not become part of the final bundle of your block.

To import these helpers, use the following syntax:

// Import a component
import { myComponent } from '@xwp/block-helpers/components';

// Import a react hook
import { myHook } from '@xwp/block-helpers/hooks';

// Import a utility function
import { myUtil } from '@xwp/block-helpers/utils';

Contributing

In order to contribute to this library, there a little bit of setup required.

1. Go to the root of this library
2. Run npm link
3. Go to a project that has a JS build process setup
4. Run npm link @xwp/block-helpers
5. Now you can use your local clone of this repository within your project

Note: This process will be streamlined in the future.

Component building guide

When building a component that intends to affect the look of a block, both within the editor and the front end, then both cases should be exported with the following pattern:

export const ExampleBlockHelper = {};

ExampleBlockHelper.Edit = (props) => {
	// Shown in block editor
};

ExampleBlockHelper.Save = (props) => {
	// Shown in the theme front end
};

Then within your block's respective location, simply reference these components like so:

<ExampleBlockHelper.Edit {...props} />
<ExampleBlockHelper.Save {...props} />

Styling components

Styling components is as simple as including the CSS/SCSS file into your JS file, with one small caveat: For the styles to appear in Save, you must inline them in your component, like so:

import styles from './styles.scss';
...
ExampleBlockHelper.Save = () => {
	return (
		<>
			<style>{ styles }</style>
			<div className="foo">Howdy</div>
		</>
	);
};

This will inline the styles in the front end, so ensure your selectors are unique. This step is not required for the Edit component.

Experimental: You may use Emotion for styling via css-in-js. This hasn't been tested thoroughly yet.

Testing

This library should only focus on unit testing these helpers. No functional or e2e testing should be done here. When interacting with a @wordpress/ package, please mock the required functionality within src/__mocks__/wordpress.js and import this file at the top of your test file.

npm test

Publishing

This library is a public NPM package. In order to publish to NPM, cut a new release on GitHub, which then triggers a GitHub Action which takes care of publishing to npmjs.com.

License

TBD.