Project Setup

Preparation

clone Builder-Blocks and copy boilerplate folder

Project Structure

Important directories / files you should know before you get started:

• src/block: Where your block lives
• src/block/block.jsonc: Metadata for your block — important to fill it out before upload so Storipress nows how to categorise your custom block. Its format is json with comment, so you can treat it as normal json file.
• src/data.js: Mock data for your block so you can better visualise your design. You can edit it for better data
• tailwind.config.js: Config file for tailwindcss. See TailwindCSS Config for instructions on how to propose a new class.
• package.json: File for metadata and dependency list. See our Dependency Policy for instructions on how to add a new dependency.

Geting Started

The boilerplate is set up using Yarn v2, but you can use NPM if you wish. Instructions for both are below

Set up

Yarn Set up

Installation instructions for Yarn can be found here. Ensure you have global yarn installed by running the below command outside of this project:

$ yarn --version
1.22.5

If you see version 1.x.x, then you're all set! Yarn v2 is already included in this boilerplate. Try to run the same command under this project:

$ yarn --version
2.4.0

After this, you can install the dependencies by running:

yarn install

NPM Set up

npm install

Development Server

yarn serve

npm run serve

Linting

Before uploading your block, ensure it passes the linter. To lint your block, run:

yarn lint

npm run lint

TailwindCSS Config

TailwindCSS is a powerful tool due to its flexibility — you can easy to add a new class by editing the config file. However, as all blocks must be built with the same config file, it is not recommended that you edit your config file in local.

New classes

If you require a new class, we recommend you use Tailwind JIT.

Tailwind JIT supports arbitrary classes via the use of square brackets. For example, to add a 20rem bottom padding, use pb-[20rem], or pb-[320px], etc.

Dependency Policy - not relevant for public docs

You can use following packages without restrictions:

• lodash : Utilities functions
• date-fns : Date manipulating and formating
• tailwindcss : Utilities-first style framework
• And of course Vue.js, but NO Vuex or vue-router

If you want to add other dependancies, it is recommended you meet the following checklist:

1. Have an Open Source License and not be GPL-like
2. It must not register anything to global (You don't need to use Vue.use)
3. If it includes css, it must not pollute global css (i.e. uses scope css, css module or including prefix for class names)
4. Try to keep it small to keep your site performant
5. The package must be Vanilla Javascript or Vue.js
6. It should not be bundeled by webpack, or it will slow your build times.
7. The package should be maintained.
8. All in all, if you can, it probably is a better idea if you reuse our existing packages

VSCode

This boilerplate includes the config files for Visual Studio Code. It may be easier for you if you use VSCode; but you can use your favorite tool(s).

For your code editor config, these are our recommended extensions:

• bradlc.vscode-tailwindcss: Integrates with tailwindcss and provides auto completion.
• dbaeumer.vscode-eslint: Integrates eslint into VSCode. With this extension, you can see eslint check result in your editor
• esbenp.prettier-vscode: Integrates prettier into VSCode. It will format your code when you save a file.
• stylelint.vscode-stylelint: Integrates stylelint into VSCode. It will help you check your styles

Checklist before you upload

1. Run yarn lint (or npm run lint) and ensure you pass the checks
2. Ensure you've have filled out the meta in the src/block/block.jsonc
3. Take a look in your devtool console (in Chrome/Firefox press F12, or Ctrl/Cmd + Shift + I) and make sure there is no error/warning from Vue
4. Ensure you've included a preview image

Naming your submission

Name the root folder of each block.

How to submit your work

To submit your work, create a Pull Request. To create a PR you have two options:

Branch in Builder-Blocks Repo

1. Clone the Builder-Blocks to your local
2. Create a new branch via git checkout -b <branch-name>
3. Copy the directory src/block of your work under the category name of your block. Ensure you rename it to follow the naming rules.
4. Commit and push current branch to Github via git push -u origin <branch-name>
5. Create a PR on the Github Repo

Private Fork

1. Fork Builder-Blocks under your Github account via PRIVATE FORK
2. Clone your fork to the local
3. Create a new branch via git checkout -b <branch-name>
4. Copy directory src/block of your work under the category name of your block. Ensure you rename it to follow the naming rules.
5. Commit and push current branch to Github via git push -u origin <branch-name>
6. Create a PR on the Github Repo