Getting Started

Installation

Requirements

• Node.js version 22 or higher or Bun
• Familiarity with the terminal to use the CLI
• Supported text editor, currently only VSCode

The fastest way to get started is using the scaffolding CLI create-weaver Make sure to have an up-to-date version of Node.js or Bun installed and your current directory is one you intend to create a project.

In your terminal, run the following command with your favorite package manager (Run without the $):

npm

$ npm create weaver@latest

pnpm

$ pnpm create weaver@latest

bun

$ bun create weaver@latest

The command will install and execute create-weaver. You will be prompted for some options to configure your project, like so:

┌  create-weaver 
│
◇  Project name:
│  thyweaver-project
│
◇  Select a storyformat:
│  ● Sugarcube
│
◇  Select addons:
│  ◻ TailwindCSS (Requires "linting")
│  ◻ TypeScript
│  ◻ Linting (Prettier and Oxlint)
│
└  Done. Now run:

  cd thyweaver-project

Then, install dependencies:

npm

$ npm install

pnpm

$ pnpm install

bun

$ bun install

The cli will be available as weaver, run the Tweego setup command next:

npm

$ npm weaver setup

pnpm

$ pnpm weaver setup

bun

$ bun weaver setup

And finally start in developer mode, a server will automatically make your project available in the browser reload when you make changes:

npm

$ npm weaver dev

pnpm

$ pnpm weaver dev

bun

$ bun weaver dev

You should now have your first ThyWeaver project running!

Standalone

ThyWeaver can be installed standalone in existing projects that have a package.json for manual migration like so:

npm

$ npm add -D @thy-weaver/core

pnpm

$ pnpm add -D @thy-weaver/core

bun

$ bun add -D @thy-weaver/core

INFO

@thy-weaver/core is an ESM-only package, don't use require() to import it, and make sure your nearest package.json contains "type": "module"

You can check-out the manual migration guide here

File Structure

Assuming you chooses to create-weaver, the generated file structure will be like so:

<your-project-name>
├── .vscode/ 
├── .tweenode/ 
├── dist/ 
├── src/ 
│   ├── assets/ 
│   │   ├── app/ 
│   │   │   └── styles/ 
│   │   ├── fonts/ 
│   │   ├── media/ 
│   │   └── vendor/ 
│   └── story/ 
├── package.json 
└── thyweaver.config.js (or .ts)

The src/ directory is considered the project root. .tweenode is auto-generated when you run weaver setup and contains the Tweego executable and story format files.

Your story source files (.twee) go in under src/story/

More details about the default file structure can be found here

The Config File

The config file (thyweaver.config.js) allows you to configure various aspects of your project and setup plugins.

thyweaver.config.js

import { defineConfig } from "@thy-weaver/core";

const config = defineConfig({
  devServer: {
    port: 3000,
    restricToLocalhost: false,
    twineDebug: false,
  },
  bundler: {
    watcherDelay: 1000,
    filesystem: {
      projectFiles: {
        entryPoint: "src/assets/app/index.js",
      },
    },
  },
});

export default config;

thyweaver.config.ts

import { defineConfig } from "@thy-weaver/core";

const config = defineConfig({
  devServer: {
    port: 3000,
    restricToLocalhost: false,
    twineDebug: false,
  },
  bundler: {
    watcherDelay: 1000,
  },
});

export default config;

Consult the Config Reference (WIP) for full details on all config options.

When your are ready to ship your game, run the following command:

npm

$ npm weaver build

pnpm

$ pnpm weaver build

bun

$ bun weaver build

This will compile your story, bundle .js and .css and copy media over to dist/.

What's Next

• To see what each command of the CLI do, proceed to CLI Reference
• To discover more about the features of ThyWeaver, see the Guide