Getting Started

← Documentation
STRVCT

Setup, integration, and first steps with the Strvct framework.

Prerequisites

  • Git (with submodule support)
  • Node.js
  • Cursor (or VSCode)

Adding Strvct to Your Project

Strvct is designed to be used as a git submodule within your project. From your project's root folder:

git submodule add https://github.com/stevedekorte/strvct.net.git strvct

If you plan to deploy on GitHub Pages, add a .nojekyll file to your root folder to prevent Jekyll processing.

Project Structure

A typical Strvct project looks like this:

your-project/
├── strvct/              # Framework submodule
├── app/                 # Your application code
│   ├── _imports.json    # Declares your app's source files
│   └── ...
├── resources/           # Icons, sounds, images
├── build/               # Generated by build (do not edit)
│   ├── _index.json      # Resource metadata catalog
│   └── _cam.json.zip    # Compressed content bundle
├── _imports.json         # Root imports (references strvct + app)
└── index.html            # Entry point

Declaring Imports

Strvct uses _imports.json files instead of standard ES module imports. Each directory that contains source files needs an _imports.json listing its files and subdirectories:

[
    "_css.css",
    "external-libs/_imports.json",
    "source/_imports.json",
    "app/_imports.json"
]

Paths are relative to the directory containing the _imports.json. Entries can be direct file paths (e.g. "MyClass.js") or references to sub-imports (e.g. "subfolder/_imports.json"). The build system recursively follows all references to discover the complete set of resources and their dependency order.

Building

The build process scans your _imports.json tree and produces two files in the build/ directory:

  • _index.json — metadata catalog with paths, sizes, and SHA-256 content hashes
  • _cam.json.zip — compressed content bundle keyed by hash

To run the build manually:

node ./strvct/source/boot/index-builder/ImportsIndexer.js

For non-code assets (icons, sounds), run the resource indexer:

node ./strvct/source/boot/index-builder/SvResourceIndexer.js ./resources/icons ./resources/sounds

If your project uses a justfile, these are typically wrapped in a just build command.

Running Locally

Start the local web server:

node ./strvct/webserver/CliWebServer.js --config path/to/config.json --port 8000

The server configuration is a JSON file specifying request handler classes:

{
    "serverName": "MyApp",
    "requestClasses": [
        "./requests/MyRequestHandler.js"
    ]
}

Use --secure true for HTTPS (you will need to accept the self-signed certificate warning on first visit) or --secure false for HTTP.

Debugging

Cursor (and VSCode) can debug Strvct applications via Chrome DevTools. Key points for your launch configuration:

  • Set webRoot to your site directory (the folder containing the strvct/ submodule)
  • Map paths with "pathMapping": { "/": "${webRoot}/" }
  • Disable source maps ("sourceMaps": false) — Strvct uses sourceURL comments instead
  • Optionally disable network cache ("disableNetworkCache": true) during development

Example .vscode/launch.json configuration:

{
    "name": "local",
    "type": "chrome",
    "request": "launch",
    "url": "https://localhost:8000",
    "webRoot": "${workspaceFolder}/site",
    "pathMapping": { "/": "${webRoot}/" },
    "sourceMaps": false,
    "disableNetworkCache": true
}

This allows breakpoints, stepping, and source display to work correctly with dynamically evaluated code.

ESLint

Strvct includes an ESLint configuration at strvct/eslint.config.js. Key rules to be aware of:

  • 4-space indentation
  • Semicolons required
  • Double quotes for strings
  • Space before function parentheses — function () not function(), methodName () not methodName()

Install ESLint if you don't have it:

npm init @eslint/config -g

Writing Your First Class

Create a file in your app directory and declare it in your _imports.json:

(class MyNode extends SvSummaryNode {

    initPrototypeSlots () {
        {
            const slot = this.newSlot("greeting", "Hello, world!");
            slot.setSlotType("String");
            slot.setShouldStoreSlot(true);
            slot.setSyncsToView(true);
            slot.setCanEditInspection(true);
        }
    }

    initPrototype () {
        this.setShouldStore(true);
    }

    init () {
        super.init();
        return this;
    }

    subtitle () {
        return this.greeting();
    }

}.initThisClass());

This creates a persistent node with an editable string property that automatically appears in the UI inspector. The framework handles view generation, storage, and synchronization — you only define the model.

Next Steps