99-reference/framework-imports.md

Framework imports

Use this file when you need to import Vroq framework modules correctly.

Main rule

Never guess framework import paths.

List the files under the active framework directory first, then import from files that actually exist.

For v01, inspect:

appid: vroq
path: vroqjs/v01/

If you need a specific file, read it before relying on its API.

Critical LLM rule

NEVER GUESS, ALWAYS CHECK THE FILES.

When creating apps, importing framework modules, or fixing errors:

1. read the app's app.json 2. determine the active framework version such as v01 3. list files in vroqjs/<version>/ 4. confirm the exact file exists 5. if you use that file, read it to learn how it works 6. when fixing errors, always do this before changing code

Do not assume an aggregator file, helper, component, or system module exists unless you have confirmed it in the framework files.

Preferred UI import pattern

For app UI code, prefer importing from:

import { VStack, HStack, Button, Text } from "/vroqjs/ui.js";

/vroqjs/ui.js is the preferred convenience entrypoint for common UI components.

Explicit component imports

Explicit imports are also valid when needed:

import { VStack } from "/vroqjs/components/VStack.js";
import { HStack } from "/vroqjs/components/HStack.js";
import { Button } from "/vroqjs/components/Button.js";
import { Text } from "/vroqjs/components/Text.js";

Use explicit imports when you need a specific component file or want to inspect the file directly.

Runtime imports

Runtime utilities come from:

import { mount, $state } from "/vroqjs/runtime.js";

Store imports

Store utilities come from:

import { createStore } from "/vroqjs/system/store/createStore.js";
import { action } from "/vroqjs/system/store/action.js";

How to learn available components

To learn what components exist in the current framework version:

1. list files in vroqjs/<version>/components/ 2. read the component files you plan to use 3. check exported names and calling patterns from those real files

Do not invent component names or props.

What to do when an import fails

When an import fails or a file returns 404:

1. stop guessing 2. list the framework files again 3. confirm the import path exists 4. read the actual file to confirm exports 5. patch the app to use a real import path 6. update docs if the mistake is easy to repeat

Final rule

Always treat the framework directory as the source of truth.

NEVER GUESS, ALWAYS CHECK THE FILES.