Project Structure
When you create a Blocklet, it follows a standard directory structure. This organization is essential as it allows Blocklet Server to correctly identify, run, bundle, and deploy your application. The blocklet init command is the simplest way to scaffold a new project with this required structure.
This guide details the purpose of each file and directory generated by the command. For a step-by-step guide on using the command, see blocklet init.
Directory Layout#
A typical Blocklet project root contains a set of conventional files and directories. The presence of these files enables the Blocklet CLI and Server to manage the application's lifecycle.
Here is a visual representation of a newly initialized Blocklet project:
Core Files and Directories#
File / Directory | Purpose |
|---|---|
| Required. The Blocklet manifest file containing all essential metadata. |
| Standard Node.js manifest for managing dependencies and scripts. |
| A Markdown file for your blocklet's detailed description, used in the Blocklet Store. |
| The icon for your blocklet, displayed in Blocklet Server and the Blocklet Store. |
| A directory to store screenshots for the Blocklet Store listing. |
| The main entry point of your blocklet, depending on its |
| A pre-configured file to exclude common temporary files from version control. |
Key Files Explained#
blocklet.yml#
This is the most important file in your project. It acts as the manifest, providing all the necessary information about your Blocklet to the server. It includes metadata such as its unique DID, title, version, and configuration for how it should be run.
package.json#
While blocklet.yml is the manifest for Blocklet Server, package.json serves its standard role in the Node.js ecosystem. You use it to define project dependencies and scripts. When you run blocklet init, the command will attempt to read existing name, description, and author fields from package.json to use as default values.
Entry Point#
The blocklet init command creates a basic entry point file based on the group you select. This file ensures your Blocklet can be started immediately after creation.
For a dapp (decentralized application) group, a simple Node.js server is created in index.js:
const http = require('http');
const server = http.createServer((req, res) => {
res.statusCode = 200;
res.setHeader('Content-Type', 'text/plain');
res.end('Hello Blocklet\n');
});
const port = process.env.BLOCKLET_PORT || 3000;
server.listen(port, () => {
// eslint-disable-next-line no-console
console.log(`Server running at http://127.0.0.1:${3000}/`);
});For a static group, a basic index.html is created to be served as a static site:
<!DOCTYPE html>
<html>
<head>
<title>Hello Blocklet</title>
</head>
<body>
<h1>Hello Blocklet</h1>
</body>
</html>.gitignore#
To keep your repository clean, a default .gitignore file is included. It excludes common files and directories that shouldn't be committed to version control, such as node_modules, build artifacts, and local environment files.
# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
# dependencies
.pnp
.pnp.js
.DS_Store
node_modules
# testing
coverage
# production
build
dist
dist-ssr
.blocklet
# local env files
*.local
# Log files
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*
lerna-debug.log*Understanding this project structure is foundational for building, testing, and deploying your Blocklets. With your project initialized, you are ready to start coding. To learn about the typical development cycle, continue to the Development Workflow guide.