Getting Started
This guide provides the essential steps to install the @blocklet/meta library and use it to perform a fundamental task: parsing a blocklet.yml file. Following these steps will get you up and running quickly.
Installation#
First, add the library to your project using either yarn or npm.
yarn add @blocklet/metaOr with npm:
npm install @blocklet/metaBasic Usage#
The primary function you'll use is parse, which reads and processes a Blocklet's metadata file from a specified directory.
Create a JavaScript file (e.g., index.js) and add the following code:
const { parse } = require('@blocklet/meta');
// The path to the root directory of your blocklet
const blockletDir = '/path/to/your/blocklet';
try {
const meta = parse(blockletDir);
console.log('Successfully parsed blocklet meta:');
console.log(meta);
} catch (error) {
console.error('Failed to parse blocklet.yml:', error.message);
}How It Works#
The parse(dir) function performs several key operations:
- Locates the file: It searches for either
blocklet.ymlorblocklet.yamlin the provided directorydir. - Reads and Parses: It reads the file content and parses it from YAML into a JavaScript object.
- Fixes and Normalizes: It automatically corrects common issues and standardizes data structures. This includes formatting person objects, resolving repository URLs, ensuring required fields are present, and converting all top-level keys to camelCase for consistency in JavaScript.
- Validates: It validates the resulting object against the official Blocklet Specification to ensure all properties are correct and well-formed. If validation fails, it throws a detailed error.
After running the script, the meta constant will hold a validated JavaScript object representing your blocklet.yml, ready for use in your application.
For example, if your blocklet.yml contains:
name: my-blocklet
version: 1.0.0
description: A sample blocklet.
spec_version: 1.0.0The output meta object would be:
{
"name": "my-blocklet",
"version": "1.0.0",
"description": "A sample blocklet.",
"specVersion": "1.0.0"
}What's Next?#
Now that you know how to install the library and parse a metadata file, you can explore the details of the metadata format and the library's other functions: