# How to create a custom block for Gutenberg Cloud

Blocks for **Gutenberg Cloud** are just normal Gutenberg custom blocks with some meta. So here you go: The quick guide to making your first custom block!

*Note: If you already know how to build a block, you can skip step 2.*

## Step 1 - Ask yourself: Do I need to make a new plugin?

Mostly, no. If you are making a neatly designed layout, or providing Gutenberg with some handy settings in the sidebar, this is all JS/HTML/CSS. By sticking to front-end code, your block can be used not only in WP, but also in Drupal (and more)!


If you are forced to use PHP for something on the server however, you can kickstart your plugin using [create-guten-block](https://github.com/ahmadawais/create-guten-block) (WP only). Even then, you  might want to open source the front-end part, so other CMSs can use it.

## Step 2 - Build a block

Let's build a “Hello World” block with some styling and sidebar settings. The easiest way to create a custom block is using the [Create Cloud Block](https://github.com/front/create-cloud-block) tool.

The [Create Cloud Block](https://github.com/front/create-cloud-block) is a boilerplate generator for building custom blocks for Gutenberg Cloud and all we have to do is run `$ npx create-cloud-block hello-world` where ‘hello-world’ is the name of our custom block. This command will generate all the files we need to build our block.

*Check generated files [here](https://github.com/SofiaSousa/hello-world/commit/5091f54683835b73813fb5d84c6a43e17cd32e93)*

Once files are generated, we can compile and run our custom block in development mode. Let’s try by going to the block folder `$ cd hello-world` and running the follow command `$ npm start`. After the editor starts running in the browser, we can insert our custom block. By default, it should look like the following.

![Insert Custom Block](../assets/insert_custom_block.gif?sanitize=true "Insert Custom Block")

Now, we can start by customizing our block! The files we should care about are in ‘src/hello-world’ folder (‘index.js’ and ‘style.css’).

In 'src/hello-world/index.js', we can change the block name to 'Hello world', add 'My first custom block for Cloud blocks' to the description and use 'format-chat' icon. Our custom block sidebar should looks like this:

![Custom Block Sidebar](../assets/custom_block_sidebar.png?sanitize=true "Custom Block Sidebar")

*Check files changes [here](https://github.com/SofiaSousa/hello-world/commit/247c1a05a32e8a9f2624ad01f9fd6efe60d5bc33)*

For now, we can change block font size and text and background color in editor. Would be nice if we also could change the text align of the block. Let’s add the align attribute!

First we have to add the new attribute to `BLOCK_ATTRIBUTES` object. Also we can set the default value.

```js
// src/hello-world/index.js

const BLOCK_ATTRIBUTES = {
  ...
  align: {
    type: 'string',
    default: 'center',
  },
};

```

Then we can use **BlocksControls** and **AlignmentToolbar** components from editor Gutenberg module to add the align options to the block toolbar.

```js
// src/hello-world/index.js

const {
  AlignmentToolbar,
  BlocksControls,
  ...
};

```

![Alignment Toolbar](../assets/alignment_toolbar.png?sanitize=true "Alignment Toolbar")

Finally we only need to set the selected align value to the block content in `edit` and `save` methods and remove the css rule by default in 'src/hello-world/style.scss'.

*Check all files changes [here](https://github.com/SofiaSousa/hello-world/commit/0b8d07d6d6f641f10eea714ce10803957a9020ae)*

After the changes we can rebuild the block and run it in dev mode by running npm start command.

## Step 3 - Submit block to Gutenberg Cloud

### Add screenshot

To improve the Gutenberg Cloud browsing experience, add a nice visual of your block in root, and list it in package.json files object (see below).

- Screenshot name: screenshot.png
- Image size: 1200px * 600px

It’s a good idea to run your png through [TinyPNG](https://tinypng.com/) to make it light.

### Publish to NPM

Make sure your README.md makes sense, and update the package.json values in gutenbergCloud object, and also `homepage`, `author` and `description`. Note that these will be visible in the UI when clicking to see More details. 

Note that you need the keywords, `gutenberg`and `gutenberg-cloud` for the block to work. Feel free to add some more, like: tags, social, map, etc.

Custom blocks generated by create-cloud-block tool come with all configuration needed to be distributed by Cloud Blocks. Also they have a deploy script which complies the build files and publish the package to NPM, so all we have to do is run `$ npm run deploy`.

After our review, your custom block is available to the world through [api.gutenbergcloud.org/blocks](https://api.gutenbergcloud.org/blocks). Congrats!

## Documentation

That’s pretty much it! Before doing anything advanced: Read the official docs. Here are some good resources:

- [Gutenberg handbook](https://wordpress.org/gutenberg/handbook/) (official docs)
- [Example blocks on Github](https://github.com/WordPress/gutenberg-examples)
- [New tutorials](http://gutenberg.news/category/tutorials/) (these get old fast)