Have ideas to improve npm?Join in the discussion! »

    @wordpress/create-block

    2.3.2 • Public • Published

    Create Block

    Create Block is an officially supported way to create blocks for registering a block for a WordPress plugin. It offers a modern build setup with no configuration. It generates PHP, JS, CSS code, and everything else you need to start the project.

    It is largely inspired by create-react-app. Major kudos to @gaearon, the whole Facebook team, and the React community.

    Description

    Blocks are the fundamental element of the WordPress block editor. They are the primary way in which plugins and themes can register their own functionality and extend the capabilities of the editor.

    Visit the Gutenberg handbook to learn more about Block API.

    Quick start

    You just need to provide the slug which is the target location for scaffolded files and the internal block name.

    $ npx @wordpress/create-block todo-list
    $ cd todo-list
    $ npm start

    (requires node version 12.0.0 or above, and npm version 6.9.0 or above)

    It creates a WordPress plugin that you need to install manually.

    Usage

    The following command generates PHP, JS and CSS code for registering a block.

    $ npx @wordpress/create-block [options] [slug]

    Demo

    [slug] is optional. When provided it triggers the quick mode where it is used as the block slug used for its identification, the output location for scaffolded files, and the name of the WordPress plugin. The rest of the configuration is set to all default values unless overridden with some of the options listed below.

    Options:

    -V, --version                output the version number
    -t, --template <name>        block template type name, allowed values: "es5", "esnext", or the name of an external npm package (default: "esnext")
    --namespace <value>          internal namespace for the block name
    --title <value>              display title for the block
    --short-description <value>  short description for the block
    --category <name>            category name for the block
    --wp-scripts                 enable integration with `@wordpress/scripts` package
    --no-wp-scripts              disable integration with `@wordpress/scripts` package
    --wp-env                     enable integration with `@wordpress/env` package
    -h, --help                   output usage information

    More examples:

    1. Interactive mode - without giving a project name, the script will run in interactive mode giving a chance to customize the important options before generating the files.
    $ npx @wordpress/create-block
    1. ES5 template – it is also possible to pick ES5 template when you don't want to deal with a build step (npm start) which enables ESNext and JSX support.
    $ npx @wordpress/create-block --template es5
    1. Help – you need to use npx to output usage information.
    $ npx @wordpress/create-block --help

    When you scaffold a block, you must provide at least a slug name, the namespace which usually corresponds to either the theme or plugin name, and the category. In most cases, we recommended pairing blocks with plugins rather than themes, because only using plugin ensures that all blocks still work when your theme changes.

    Available Commands

    When bootstrapped with the esnext template (or any external template with wpScripts flag enabled), you can run several commands inside the directory:

    $ npm start

    Starts the build for development. Learn more.

    $ npm run build

    Builds the code for production. Learn more.

    $ npm run format

    Formats files. Learn more.

    $ npm run lint:css

    Lints CSS files. Learn more.

    $ npm run lint:js

    Lints JavaScript files. Learn more.

    $ npm run packages-update

    Updates WordPress packages to the latest version. Learn more.

    Note: You don’t need to install or configure tools like webpack, Babel or ESLint yourself. They are preconfigured and hidden so that you can focus on coding.

    External Templates

    Since version 0.19.0 it is possible to use external templates hosted on npm. These packages need to contain .mustache files that will be used during the block scaffolding process.

    Template Configuration

    It is mandatory to provide the main file (index.js by default) for the package that returns a configuration object. It must contain at least the templatesPath field.

    templatesPath

    A mandatory field with the path pointing to the location where template files live (nested folders are also supported). All files without the .mustache extension will be ignored.

    Example:

    const { join } = require( 'path' );
    
    module.exports = {
    	templatesPath: join( __dirname, 'templates' ),
    };

    assetsPath

    This setting is useful when your template scaffolds a block that uses static assets like images or fonts, which should not be processed. It provides the path pointing to the location where assets are located. They will be copied to the assets subfolder in the generated plugin.

    Example:

    const { join } = require( 'path' );
    
    module.exports = {
    	assetsPath: join( __dirname, 'assets' ),
    };

    defaultValues

    It is possible to override the default template configuration using the defaultValues field.

    Example:

    module.exports = {
    	defaultValues: {
    		slug: 'my-fantastic-block',
    		title: 'My fantastic block',
    		dashicon: 'palmtree',
    		version: '1.2.3',
    	},
    	templatesPath: __dirname,
    };

    The following configurable variables are used with the template files. Template authors can change default values to use when users don't provide their data:

    WP-CLI

    Another way of making a developer’s life easier is to use WP-CLI, which provides a command-line interface for many actions you might perform on the WordPress instance. One of the commands wp scaffold block was used as the baseline for this tool and ES5 template in particular.



    Code is Poetry.

    Install

    npm i @wordpress/create-block

    DownloadsWeekly Downloads

    215

    Version

    2.3.2

    License

    GPL-2.0-or-later

    Unpacked Size

    89.8 kB

    Total Files

    31

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar