Imports

Vertex has a file-based module system: each .vtx file is a module. Imports are resolved by both vertex build (for compiling to Apex classes) and vertex run (for local JIT execution and --sf anonymous Apex runs).

Import forms

Bare import. Access the module’s public symbols via a qualifier:

import accounts
import billing.invoices         // nested path: qualifier is last segment

let acc = accounts.findById("001")
let inv = invoices.create()   // qualifier is the last segment

Aliased import. Choose your own qualifier:

import billing.invoices as inv

let i = inv.create()

Selective import. Bring specific symbols directly into scope:

import accounts.{ findById, Account }

let acc = findById("001")       // bare call, no qualifier needed

Module path → Apex class name

The module path maps to an Apex class name:

Module path	Apex class name
accounts	Accounts
billing/invoices	Billing_Invoices
lang/greeter	Lang_Greeter

The generated outer class always includes an Apex sharing modifier (see Annotations). The default is with sharing:

public with sharing class Accounts { ... }
public with sharing class Billing_Invoices { ... }

Cross-module function calls emit as TargetClass.fnName(args). Selectively imported types emit as TargetClass.TypeName in Apex.

vertex run and imports

vertex run supports imports directly. No build step required for local scripts.

No imports → no project needed. A file with no import declarations runs anywhere, just like dart run on a standalone Dart file.

With imports → project discovery. When the entry file contains imports, vertex run walks upward from the entry file’s directory looking for sfdx-project.json. The directory that contains that file becomes the project root, and <projectRoot>/src/ is the module tree. Only the transitively reachable modules are loaded; unrelated files in src/ are never touched.

my-project/
  sfdx-project.json
  src/
    greeter.vtx       ← loaded (imported by the script)
    unrelated.vtx     ← skipped
  scripts/
    hello.vtx         ← entry file

scripts/hello.vtx

import greeter.{ greet }

debug greet("World")

vertex run scripts/hello.vtx

--sf with imports. When using --sf with an entry script that has imports, the workspace must already be built and deployed before running:

vertex build
sf project deploy start --target-org <alias>
vertex run --sf --org <alias> scripts/hello.vtx

The generated anonymous Apex references the deployed Apex classes directly (e.g. Greeter.greet("World")). If a referenced class is not deployed, the org returns a runtime “unknown class” error.

The entry file is a script, not a module. It may contain top-level statements and a trailing expression. It is excluded from the module graph even if it lives under src/. Other modules cannot import the entry file.

Visibility

Only pub declarations are importable. Calling a non-pub symbol from another module is a compile error (E124).

Error codes

Code	Meaning
E122	Module not found (no matching .vtx file)
E123	Symbol not found in module’s public API
E124	Attempted access to a private declaration
E125	Cyclic import detected
E126	Name conflict: same symbol selectively imported from two modules
E127	Variant constructor called on opaque type outside its module
E128	Field accessed on opaque type outside its module
E129	Variant pattern matched on opaque type outside its module
E130	Record update used on opaque type outside its module