Getting started

From a machine with nothing on it to a page you wrote, running locally.

1. Install the toolchain

Download vsa-installer and run it, or run the same thing straight from the site with the line below. Either way it installs git, PHP 8.3, Composer, Node, the PHP extensions and the vsa command itself.

While the VSA repositories are private it asks once for a GitHub token and remembers it — see making a token. Setting VSA_TOKEN beforehand skips the prompt, which is what a CI job has to do.

macOS

curl -fsSL https://vsa.vectorasoft.com/vsa-installer.sh | bash

Windows is the same idea in PowerShell, per-user through Scoop and with no administrator rights — the download page has both commands and every option.

Then open a new terminal, so the PATH change reaches it.

2. Create a project

vsa new takes the template, renames it to your product, renames the first app, starts a fresh git repository with one commit, and runs setup.

Terminal

vsa new acme-hr --name="Acme HR" --app=hr
cd acme-hr

Useful variations:

--port=8093 — the port vsa serve will use
--remote=<git url> — set the origin as part of creating it
vsa setup — what you run instead after git clone of an existing project
vsa init — adopt an app that already has the VSA structure but predates the CLI

3. Run it

Terminal

vsa serve

A PHP server on 127.0.0.1, with a browser reload and a vsa check run on every save. Before it starts, the app is booted once and its shells rendered to verify which asset mode it is in — raw sources or built chunks — so a mismatch is caught here rather than after a deploy.

vsa doctor is the command to reach for when something is off. It reports the CLI version, the tools, the PHP extensions, which .env keys are missing (never their values), the git hooks, and whether the database, XAuth and the CDN are reachable.

A project that serves several subscribers needs one in the URL before it will show a login — set DEV_SUBS_CODE in .env and every untenanted address redirects to the tenanted one, so you never type /<app>-<code> by hand. Use the code your local auth database has; a wrong one is a 404 by design. See Routes & tenancy.

4. Add a page

A page is not just a file. make:page writes the component and its blade, registers it in the app file, gives it a place in the menu, and adds its translation keys. A list page also gets a controller, a model and an API route.

Terminal

vsa make:page hr EmployeesComponent --type=list --nav=menus.people

Option	Meaning
`--type=list\|form\|blank`	A list screen (search, filters, ListView, add/edit dialog), a single-record form, or an empty page. The first two create the API too
`--api` / `--no-api`	Force the controller, model and route on or off
`--nav=menus.x`	Where it appears in the sidebar
`--module=<id>`	The XAuth module that guards it

Renaming and removing are commands too, because a page's name appears in half a dozen places: vsa rename:page shows a plan first, and vsa rm:page refuses while another file still uses it.

A report is not a page: it is two declarations in the app file and one handler class, opened from the one Report Center screen. vsa make:report writes both ends — see Reports.

5. Before you commit

The project's pre-commit hook runs vsa check, so most of this happens whether you ask for it or not.

Terminal

vsa i18n:sync      # every key the code uses exists in every locale
vsa check          # the rules; exit 1 on any error
vsa permissions    # what each page and button actually checks

Rules & checks lists each rule and the defect that caused it to exist.

6. Build for a deploy

Terminal

vsa build          # hashed, minified chunks + source maps + manifest.json in public/dist
vsa serve --built  # serve those chunks locally, before the deploy
vsa cache:bust     # after deploying in raw mode, refetch the changed files (commit it)

CDN files are never inlined into a chunk — they stay version-pinned tags. Built chunks do not need cache:bust, because the file name is its hash.

← Overview Commands →