Project Templates & Commands

Scalus ships two Giter8 templates for scaffolding a new project, and the generated projects come pre-wired with commands for building, testing, profiling, generating CIP-57 blueprints, and deploying contracts on-chain.

Every generated project is dual-build: it works with both sbt and Scala CLI , sharing one flat source layout (sources at the project root, test sources using the .test.scala suffix).

Templates

Template	Command	What you get
`hello.g8`	`sbt new scalus3/hello.g8`	Minimal “Hello, Cardano!” spending validator with unit and integration tests.
`validator.g8`	`sbt new scalus3/validator.g8`	Full DApp starter: validator, `Contract` (blueprint + deploy), unit and integration tests.

Start with hello.g8 to learn the basics; reach for validator.g8 when you want the full toolchain (CIP-57 blueprint generation and on-chain deployment) ready to go.

`hello.g8` layout


hello-cardano/
├── HelloCardano.scala             # Plutus V3 spending validator
├── HelloCardano.test.scala        # Unit tests (ScalaTest + scalus-testkit)
├── HelloCardanoIntegration.test.scala  # Submit-based tests (emulator / Yaci DevKit)
├── HelloCardanoContract.scala     # Contract: compiled script + CIP-57 blueprint
├── project.scala                  # Scala CLI build configuration
├── build.sbt                      # sbt build configuration
└── Readme.md

`validator.g8` layout

The validator.g8 template prompts for a name (default My Validator) and names the files after it:


my-validator/
├── MyValidator.scala              # On-chain validator — replace its body with your logic
├── MyValidator.test.scala         # Unit tests using scalus-testkit's ScalusTest
├── MyValidatorIntegration.test.scala  # Submit-based tests (emulator / Yaci DevKit)
├── MyValidatorContract.scala      # Contract: compiled script + CIP-57 blueprint
├── project.scala                  # Scala CLI build configuration
├── build.sbt                      # sbt build configuration
└── Readme.md

Build & test commands

The standard commands behave exactly as they do in any sbt or Scala CLI project. From the project directory:

sbt

Command	Purpose
`sbt compile`	Compile the on-chain and off-chain sources.
`sbt test`	Run all tests (unit + integration; uses the emulator backend).
`sbt "testOnly *HelloCardanoTest"`	Run a single test suite by name (wildcards allowed).
`sbt clean`	Remove `target/` build artifacts. Use it to force a full rebuild if you hit stale-class issues.

Quotes are required around testOnly (and any command with arguments) so sbt receives the whole string as one command.

Command	Purpose
`scala-cli compile .`	Compile the project.
`scala-cli test .`	Run all tests.
`scala-cli test . --test-only 'HelloCardanoTest'`	Run a single test suite.
`scala-cli fmt .`	Format sources with Scalafmt.
`scala-cli clean .`	Clear the Scala CLI build cache.

Speeding up sbt

Each sbt <command> boots a fresh JVM. Two ways to avoid paying that startup cost every time:

sbtn — a thin native client that talks to a persistent sbt server, keeping the JVM warm between invocations. Use it as a drop-in replacement: sbtn compile, sbtn test, sbtn "testOnly *HelloCardanoTest". Run sbtn shutdown to stop the background server.
The sbt shell — run sbt with no arguments to drop into its interactive prompt, then type compile, test, testOnly … directly (no sbt prefix, no surrounding quotes). The JVM is reused for the whole session.

One caveat: a warm server or shell reads environment variables like SCALUS_TEST_ENV and SCALUS_PROFILE once, at startup, and reuses them for its whole life — so setting one on a later command has no effect. To switch backends or toggle profiling, set the variable on a plain sbt <command> (fresh JVM each time), or restart the server (sbtn shutdown) or shell first.

Test backends

The integration tests (*Integration.test.scala) run against a backend selected by the SCALUS_TEST_ENV environment variable — emulator (the default) or yaci:


sbt test                           # in-memory emulator (the default)
SCALUS_TEST_ENV=emulator sbt test  # in-memory emulator, named explicitly
SCALUS_TEST_ENV=yaci sbt test      # a local Yaci DevKit node (auto-started; requires Docker)

The same variable works with Scala CLI (SCALUS_TEST_ENV=yaci scala-cli test .), since the test code reads it directly rather than relying on an sbt-only command.

See Emulator and Local Devnet for what each backend does and when to use it.

Profiling

Set SCALUS_PROFILE=1 to run the tests with on-chain execution profiling enabled. It writes an interactive HTML report (CPU and memory budget per source line) to target/profile.html:


SCALUS_PROFILE=1 sbt test

The same variable works with Scala CLI (SCALUS_PROFILE=1 scala-cli test .). Open target/profile.html in a browser to see where your validator spends its execution budget. See Profiling for how to read the report and optimise from it.

Blueprint & deploy

The sbt build enables the ScalusSbtPlugin, which adds two tasks backed by the Contract object in your project:


# Generate a CIP-57 blueprint under
# target/scala-3.3.7/resource_managed/main/META-INF/scalus/blueprints/
# (sbt package / publish also embed it in the JAR automatically)
sbt blueprint
 
# Deploy the validator as a reference-script UTxO
# (needs a Blockfrost key and a funded wallet)
export BLOCKFROST_API_KEY=...        # or pass --blockfrost-key
export CARDANO_MNEMONIC="word1 ..."  # or pass --mnemonic
sbt "deploy MyValidatorContract --network preview"

These two tasks are the heart of the Scalus sbt plugin. The SBT Plugin page documents blueprint verification, the full set of deploy flags, and how to wire the plugin into an existing (non-template) project.

Next steps

Write Smart Contracts — validators, data conversion, compilation
SBT Plugin — blueprint verification and contract deployment in depth
Testing — unit, property-based, and emulator-based testing
Build Transactions — construct and submit transactions