Installation
Install the essence command three ways, add the VS Code extension, and see what each of its commands does.
The Essence toolchain is one npm package to install, @essence-lang/cli. It brings the compiler, the test runner, the formatter, a language server for editors and a debug adapter for stepping through a program, as packages it depends on. They are published as compiled JavaScript, and run on Node 22 or newer, or on Bun. You can add the package to a project, install it once for every project, or run it without installing anything.
Add it to a project
A development dependency is the usual place for a compiler. The lockfile records the exact version, so every machine that installs the project compiles with the same compiler. Pick your package manager once: every block that has a tab for it follows your choice.
The install gives the project an essence command. How you reach it differs between package managers:
--version prints the version you installed. For the release these pages describe, that is:
If a version comes back, the toolchain is installed. Every command on these pages is written as a bare essence, so with a project install put your manager’s prefix in front of it. A script in package.json runs essence with no prefix.
Yarn 2 and later install packages with Plug’n’Play, a layout that replaces node_modules with a resolver map. It is their default, and the compiler cannot build under it. yarn essence --version works, but on Yarn 4.18 yarn essence build stops with an internal error:
[internal-error]
Error: Internal Compiler error: ENOENT: no such file or directory, open 'bundler/index.d.ts'Switch the project to a node_modules folder and install again:
yarn config set nodeLinker node-modules
yarn installYarn 1 installs into node_modules by default, and works as it is.
Install it once for every project
A global install suits trying the language out, or .es files that are not part of a JavaScript project. Afterwards essence is on your path, which is how every command on these pages is written.
pnpm and Bun keep global commands in a directory of their own. When that directory is missing from your path, each tells you what to do. pnpm asks you to run pnpm setup; Bun prints the export PATH=… line to add.
Yarn 1 installs globally with yarn global add @essence-lang/cli. Yarn 2 and later have no global install: yarn global was removed and has no replacement. With them, add the toolchain to the project.
Run it without installing
--package is needed because the package and the command it carries have different names. The package installs two commands, essence and esc, and neither is called cli. Without --package, npm looks for a command named after the package, finds two others, and refuses to guess:
npm error could not determine executable to runDropping --package @essence-lang/cli does not work either. Outside a project that has the toolchain installed, npx essence asks npm for a package called essence, and that name belongs to an unrelated package.
bunx picks essence on its own, so the rest of the command follows the package name directly. Anything after essence works as it does with an installed copy: npx --package @essence-lang/cli essence run hello.es compiles a file and runs it. Your first program writes that file.
yarn dlx has no tab here. It installs with Plug’n’Play, so it runs essence --version but not a build.
The VS Code extension
The VS Code extension is essence.essence-language on the Visual Studio Marketplace, listed as Essence. Install it from the Extensions view, or from a terminal:
code --install-extension essence.essence-languageNothing has to be on your path for the language features. The language server ships inside the extension. It runs on the Node that VS Code carries, the way VS Code’s TypeScript support works without a typescript package installed. Every feature and setting is on Editor setup.
Only debugging needs the essence command, and a Node to run your program on. The extension uses the essence.cli.path setting when you set it, then a checkout open in the workspace, then an essence on your path. A project install is not on your path, so point essence.cli.path at node_modules/@essence-lang/cli/bin/essence.js.
The extension is not on Open VSX, the registry VS Code’s forks install from. For those editors, build the .vsix file from a checkout, as below.
Commands
essence help lists every command, and essence help <command> describes one in full, every documented flag included.
| Command | Alias | What it does |
|---|---|---|
build | b | Compile Essence sources to JavaScript |
run | Compile a source file and execute it immediately | |
check | Type-check sources without writing any output | |
watch | w | Recompile automatically whenever a source changes |
test | t | Compile the tests and run them |
init | Write the file a project's settings live in | |
format | fmt | Format Essence sources in place |
lsp | Start the Essence Language Server, speaking over stdio | |
dap | Start the Essence Debug Adapter, speaking over stdio | |
help | Show help for essence or for a single command |
essence hello.es, with no command, is essence build hello.es. The flags each command takes are on the page each row links to.
esc is a second name for the same program, with the same commands and flags. The standalone esfmt, esls and esdap belong to the packages that implement them. In a project install, npm, Yarn 1 and Bun link them into node_modules/.bin, and pnpm does not. A global install puts only essence and esc on your path. essence format, essence lsp and essence dap always work.
essence init writes an optional essence.json, the file that holds a project’s settings. A folder of .es files needs no such file, and Projects and essence.json says when you want one.
A second package, @essence-lang/client, is on npm for JavaScript code that loads Essence modules and calls them. Calling Essence from JavaScript is its guide.
What a build writes
essence build turns each file you name into one self-contained ES module. The parts of the Essence runtime the program uses are bundled into it, and it imports no package. It runs with no node_modules beside it:
essence build hello.es
node hello.jsThe output lands beside its source, as hello.js, unless a flag names another path. It carries no import or export of its own, so no "type": "module" is needed anywhere. Bun runs the same file with bun hello.js.
Compared with JavaScript.
essence check hello.es
essence build hello.esnpx tsc --noEmit
npx esbuild hello.ts --bundle --format=esm --outfile=hello.jsessence check does what tsc --noEmit does: it reports errors and writes nothing. essence build is closer to esbuild --bundle than to tsc, which writes one output file per source file. More: Coming from JavaScript › Tooling.
Building from a checkout
Build from a checkout to work on the language itself, or to run changes made since the last release. It needs git, and Bun at the version the repository’s .bun-version file names:
git clone https://github.com/alexandertrefz/essence.git
cd essence
bun installThere is no build step. Every package the toolchain runs points its entry at its source, and Bun runs the sources as they are, so installing the workspace installs the compiler. bun install links essence into node_modules/.bin, so from inside the repository:
bun run essence --versionThe executable itself is packages/cli/bin/essence, and it runs on Bun. A script outside the repository can call it by its full path:
/path/to/essence/packages/cli/bin/essence helpA checkout also packages the VS Code extension. The .vsix it writes is self-contained, with the language server bundled into it: