blocklet-converter

Blocklet Converter

Converts static web projects and Next.js applications into ArcBlock blocklets with proper configuration and validation.

Parameters

did (required): Pre-generated blocklet DID (format: z8ia...)

Example: "Convert this project to blocklet using DID z8ia4e5vAeDsQEE2P26bQqz9oWR1Lxg9qUMaV"

If missing or invalid, exit immediately with error message: "Blocklet DID parameter is required."

Workflow

1. Project Analysis

Skip directories: node_modules/, .pnpm/, .yarn/, .cache/, .turbo/, bower_components/

Verify Web Application Exists

Check for ANY of:

• package.json with web-related dependencies
• index.html in root, public/, or src/ or common locations
• Web framework config (vite.config.*, webpack.config.*, next.config.*, etc.)

If none found → EXIT with error message: "No web application detected."

Detect Project Type

Check package.json dependencies for:

• Next.js: next in dependencies → Next.js project
• Backend frameworks: express, koa, fastify, nest, etc. → EXIT with error: "Only static webapp and next.js projects are supported."
• Otherwise → Static webapp

Extract & Emit Metadata (Early)

Immediately after confirming project type, extract metadata from package.json:

• title: Human-friendly project name suitable for public display (e.g., my-cool-app → My Cool App)
• description: A clear, non-technical description for end users. If package.json description is too technical, rewrite it to be user-friendly.

Emit using the protocol below, then continue with the workflow:

<<<BLOCKLET_PROJECT>>>
{"title": "...", "description": "..."}
<<<END_BLOCKLET_PROJECT>>>

Build (if build script exists)

bun install && bun run build

If either fails → EXIT with error output.

Locate Output Directory

For Next.js projects: Output directory is always .next — skip detection.

For static webapps: Find index.html in: dist/ → build/ → out/ → public/ → ./, or any other common locations. If not found → EXIT with error message: "No index.html entry point found."

Confirm Output Directory

Verify the output directory exists and contains expected files before proceeding.

2. Asset Preparation

• README.md: If missing, generate from {baseDir}/templates/README-template.md
• logo.png: If missing, copy from {baseDir}/assets/default-blocklet-logo.png
• index.js (Next.js only): Copy {baseDir}/assets/nextjs-entry.txt to project root as index.js

3. Generate blocklet.yml

For Next.js projects: Use template from {baseDir}/templates/nextjs-blocklet.yml

For static webapps: Use template from {baseDir}/templates/static-blocklet.yml

Populate with:

• did and name: Use provided DID
• title: Human-readable project name
• description: From package.json

4. Verification

blocklet meta

For Next.js projects:

blocklet bundle --simple --create-release --external="*"

For static webapps:

blocklet bundle --create-release

Fix any errors and retry.

5. Finalization

Do NOT output any summary or recap after completion. Simply end silently after successful verification. The tool outputs already provide sufficient feedback to the user.

Error Reference

See {baseDir}/errors.md for all error conditions and suggestions.

Supporting Files

• assets/default-blocklet-logo.png - Default logo
• assets/nextjs-entry.txt - Next.js entry point sample
• templates/static-blocklet.yml - Static webapp config template
• templates/nextjs-blocklet.yml - Next.js config template
• templates/README-template.md - README template
• examples.md - Workflow examples
• errors.md - Error reference

{baseDir} resolves to the skill's installation directory.

Output Protocol

This skill emits structured data that callers can parse programmatically.

Project Metadata Event

Emitted immediately after project validation succeeds (before build):

<<<BLOCKLET_PROJECT>>>
{"title": "...", "description": "..."}
<<<END_BLOCKLET_PROJECT>>>