Once you have all the necessary tools installed for block development,
you can start developing your first block.
In this lesson you will learn about a tool called CreateBlock,
which will allow you to quickly scaffold your first block plugin.
You will learn why you should use CreateBlock,
how to use it, and review the code that it generates.
Like any software development project, developing a block for WordPress requires a combination of
specific files and folders to be set up in a certain way.
There are multiple ways to do this,
but you would ideally want to build your block following certain best practices.
CreateBlock is a command line tool that helps you to scaffold a new block plugin
following these practices.
In software development, scaffolding is the process of creating a basic structure for a project
so that you can build on top of it.
Using CreateBlock, you can run a single terminal command to create a new block plugin,
and CreateBlock will set up the necessary files and folders for you,
following the best practices for block development.
While it is not a requirement to develop a block as part of a plugin,
it is generally the recommended approach.
One of the main reasons for this is that custom blocks are not allowed in the themes
that are submitted to the wordpress.org theme directory.
However, if you are developing a theme for your own use or for a client,
you can include custom blocks in your theme.
The difference is that you register the blocks in a different way.
Ultimately, though, the block development experience and tooling is designed to work
best with plugins, and so that's what this series of lessons will follow.
For the purposes of this series of lessons, you will be building a copyright date block.
It is a basic yet practical block that has the following features.
It displays the text copyright followed by the copyright symbol,
and then a starting year and the current year.
The user should be able to adjust the alignment of the block on the page.
It should have a one pixel solid dark border around it with about five pixels of padding,
and the user should be able to adjust the starting year.
To scaffold your first block, open the terminal on your computer and switch to the wp-content
plugins directory of your local WordPress installation.
Generally, this is done by running the following command.
CD, and then the path to your local development environment,
the path to the local installation, wp-content, plugins.
Then run the create block command and include a plugin slug.
The slug is the unique name of the plugin you want to create.
npx @wordpress/createblock@latest and then the slug.
If you're asked to confirm the installation of the create block package,
you can type yes and press enter.
Otherwise, this will create a new plugin in the copyright date block directory.
Install any required packages and create the necessary files.
Once the new plugin is scaffolded, you should have a new plugin folder in your WordPress install
named after the slightly defined.
So if we type ls, we can see copyright date block.
If you browse your WordPress dashboard and navigate to the plugin screen,
you should see your new plugin listed there.
Activate it and once it's active, create a new post.
You should be able to add your newly scaffolded block to the editor.
Take a look at what the scaffolded block plugin looks like by opening the copyright
date block directory in your code editor.
There are three directories.
The build directory is where the final deployable build of the block code is located.
This is the code that powers the block when it's used in the editor.
You generally never need to touch this directory or any of the files in it.
The node modules directory is where all the node.js packages are located.
These are also known as the project dependencies and you only need this for local block development.
The SRC or source directory is where you will spend most of your time writing block code.
This is the directory that contains the files that you will use to develop your block.
These are ultimately compiled into the code in the build directory.
After these three directories, there are a number of files.
The editor config file is for unifying the coding style for different editors and IDEs.
Yet ignore is used by the git version control system to manage what code is committed to version
control. The purposes of these files is outside the knowledge needed for block development.
So if you don't know what they're used for, you can safely ignore them for now.
If you don't see these two files for some reason, you may have to enable hidden files in your
directory browser or code editor. Next up is the copyright date block.php file.
This is the main plugin file that initiates the execution of the plugin.
Inside this file, you'll see the standard plugin header and the PHP code that registers the block.
Here the copyright date block copyright date block block init function calls the register
block type function, passing the path to the previously mentioned build directory as a
parameter. This function is then hooked into the init action as a callback.
Next, you'll see the package lock.json file and the package.json file.
The package.json file is a file that NPM uses when developing a JavaScript project.
It contains important details about your project, including any scripts that can be run on the
project and any project dependencies. Dependencies are the external packages or modules that your
project needs to run properly. For the purposes of block development, the dependency you need
is a development dependency on the WordPress scripts package. These dependencies are what
are installed inside the node modules directory. The scripts object contains a list of command
line scripts that can be run during development. Most important of these are bold, which compiles
the files from the source directory into the build directory, and start, which starts a development
server that watches for changes to the files in the source directory and automatically compiles
them into the build directory. You will learn how to use these scripts when you start developing your
block. The package lock.json contains a list of all the install dependencies, as well as the version
number of the dependency used. It locks the required dependencies to the version number
specified in this file. This is another file you can ignore for now. Finally, there is the readme.txt
file, which you will only need to edit if you intend to publish your plugin to the WordPress
plugin directory. All of your block development takes place in the source directory. Let's take
a look at the files that have been scaffolded. Block.json stores the metadata for the block,
defined as a JSON object. You can learn more about block metadata in the block metadata
handbook page in the block developer handbook. This file allows you to define things like the
block name, title, icon, and various files that make up the block, and much more.
Edit.js is where you'll spend most of your time as you work on a block.
This file exports a React edit component that is rendered in the editor
and determines how the block appears and functions in the editor.
Editor.scss contains the styles that control the appearance of the block in the blocked editor.
Usually, you will want the block to appear the same in the editor as it does on the frontend,
so you'll often not need this file at all.
Index.js is the starting point for the JavaScript execution of the block.
It sets up and executes the register block type function to register the block in the editor.
Save.js exports a save function which determines the markup that will be saved
to the post content field in the post table when the post or page is saved,
and therefore determines how the block appears and functions in the frontend.
Style.scss contains the styles that control the appearance of the block in the editor and the
frontend. Styles here can be overridden by styles in editor.scss if you need the block to appear
different in the editor. View.js is a file that is used to add any additional JavaScript to the block
on the frontend. This is another file that you will often not use. During development, you will
execute the scripts you saw in the package.json file to compile the files from the source directory
into the build directory. The process of building your block code, also known as bundling your code,
is the process of converting your code into a format that is compatible with all browsers.
When you scaffolded the block, the create block tool also ran the build process,
generating the build directory for you.
You will notice that some files are bundled into the build directory as is,
like the block.json file, while others are converted, like the index.js file.
There are also additional files like the index.asset.php that are generated during the build process.
When WordPress loads your block in the editor or in the frontend,
it's executing the code from the build directory. The WordPress scripts package,
defined as a dev dependency in the package.json file, uses a tool called Webpack to bundle your
block code. The details of how this works is outside the scope of this lesson, but you can
learn more about it in the Webpack documentation. To learn more about the create block tool,
as well as all the different options it offers, check out the package reference for create block
in the block editor handbook.