Hikkaku

Docs | Playground

Scratch with TypeScript.

Installation

bun add hikkaku # Bun
deno add npm:hikkaku # Deno
pnpm add hikkaku # pnpm
yarn add hikkaku # Yarn
npm install hikkaku # npm

Scaffold with create-hikkaku

Generate a new project from the official template (templates/base):

npx create-hikkaku@latest my-hikkaku-app
# or
bunx create-hikkaku@latest my-hikkaku-app

Common options:

• -y, --yes: skip prompts and use defaults
• --pm <pm>: force package manager (bun, deno, npm, pnpm, yarn)
• --agents, --no-agents: include or exclude AGENTS.md
• --link-claude, --no-link-claude: create or skip CLAUDE.md -> AGENTS.md
• --skills, --no-skills: run or skip skills setup after scaffolding
• --ref <git-tag>: use a specific template tag (default: create-hikkaku@<version>)

After scaffolding:

cd my-hikkaku-app
bun install
bun dev

Usage

Basic Usage

import { Project } from 'hikkaku'
import { IMAGES } from 'hikkaku/assets'
import {
  getMouseX,
  gotoXY,
  procedureBoolean,
  procedureLabel,
  whenFlagClicked,
  forever,
  switchCostumeTo,
} from 'hikkaku/blocks'

const project = new Project()

const sprite1 = project.createSprite('Sprite1') // create sprite
const cat1 = sprite1.addCostume({
  ...IMAGES.CATCHER_A,
  name: 'cat1',
}) // create costume

sprite1.run(() => {
  // event blocks (hat blocks) should be inside run() directly
  whenFlagClicked(() => {
    // this scope is for when flag clicked
    gotoXY(0, 0) // go to x:0 y:0
    switchCostumeTo(cat1) // switch costume to cat1
    forever(() => {
      gotoXY(getMouseX(), 0) // follow mouse x
    }) // control block. This can nest other blocks.
  })
  // or other event blocks
})

console.log(project.toScratch()) // get Scratch project JSON

By runnning this code, you will get a Scratch project JSON that you can load in Scratch editor.

With Vite

Integrate Hikkaku with Vite to develop Scratch projects with hot-reloading.

Put vite.config.ts in your project root:

import hikkaku from 'hikkaku/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    hikkaku({
      entry: './src/main.ts',
    }),
  ],
})

Then, put your Scratch project code in src/main.ts:

import { Project } from 'hikkaku'
import { IMAGES } from 'hikkaku/assets'
import { moveSteps, whenFlagClicked } from 'hikkaku/blocks'

const project = new Project()

const cat = project.createSprite('cat')

cat.addCostume({
  ...IMAGES.CAT_A,
  name: 'cat-a',
})
cat.run(() => {
  whenFlagClicked(() => {
    moveSteps(10)
  })
})

export default project

bun vite and open http://localhost:5173 to see your Scratch project in action!

You can HMR powered by Vite Environment API:

https://github.com/user-attachments/assets/1ff5d190-f8ee-46c4-bc78-8dbdf2879e15

Vibe Code with skills

Hikkaku has a skills for AI Agents, so you can vibe code with AI such as Codex, Claude Code, OpenCode and etc.

bunx skills add pnsk-lab/hikkaku/packages/skill # Bun
deno run -NRWE --allow-run="git" --allow-sys="homedir" npm:skills add pnsk-lab/hikkaku/packages/skill # Deno
pnpx skills add pnsk-lab/hikkaku/packages/skill # pnpm
yarn dlx skills add pnsk-lab/hikkaku/packages/skill # Yarn
npx skills add pnsk-lab/hikkaku/packages/skill # npm

Build project

With Vite Plugin:

vite build