Elide Projects

Elide is capable of creating and managing Elide-native projects through a project toolchain.

An Elide Project consists of:

1. Project manifest - elide.pkl is a powerful configurable Pkl-based manifest.
2. Work directory - .dev acts as an internal directory, that Elide uses to store output and intermediate states of build tasks.
3. Lockfile - .dev/elide.build.bin and .dev/elide.lock.v2.bin are read-only binary files used by Elide tooling. Generally, users shouldn't edit them.

Project CLI

There are three CLI commands that can depend on an Elide project to work, which they can access in two ways:

1. Direct passing - by passing --project PATH you can specify the manifest that will be loaded for this command.
2. Auto-detection - if no path is provided, the command will attempt to find a project manifest in the current directory.

As such a plain call of,

 elide build

will attempt to search for manifest in a local directory, while

 elide build -p PATH

will try to fetch the manifest from the path.

Building a Project

It's possible to view a full list of tasks that a build command generates from the project manifest.

 elide build --inspect

To run a specific task,

 elide build TASK

For example,

 elide build compile-java-main

Elide Project Manifest

The project manifest has a regimented, yet flexible structure.

# Importing project schema
amends "elide:project.pkl" 

# Importing configuration-specific schema
import "elide:Sources.pkl" as Src

# Project metadata
name = "project"
version = "1.0.0"
description = "example project"

# Project configuration
sources {
  ["main"] = new Src.SourceSetSpec {
    paths {
      "src/main/java<<>>*.java"
    }
  }
}

Project Metadata

Build Context

amends "elide:project.pkl"
import "pkl:semver"
import "elide:Sources.pkl" as src

sources {
  when (elide.version.isGreaterThan(semver.Version("1.1.0"))) {
    ["main"] = new src.SourceSetSpec {
      paths {
        "src/main/kotlin<<>>*.kt"
      }
    }
  }
}

Similarly, elide.channel lets you gate configuration on the release channel:

when (elide.channel == "release") {
  // release-only settings
}

Sources

For Elide project to build, sources have to be specified in the manifest. A general template of declaring sources is

import "elide:Sources.pkl" as Src
sources {
  ["main"] = new Src.SourceSetSpec {
    paths {
      "src/main/java<<>>*.java"
    }
  }
}

The import allows you to use source schema and helps Elide to parse the source section of the manifest.

Sources themselves are declared by paths, which are a list of pattern-matched paths.

Test source sets are compiled with test dependencies and run by elide test. JVM test coverage is configured under testing { coverage { jvm { … } } }, which can emit HTML, XML, and CSV reports.

Entrypoint

Specifying an entrypoint allows Elide to automatically detect scripts to run.

entrypoint {
  "some.entry"
}

As such if during elide run no script was specified, Elide will attempt to fetch an entrypoint filepath from the manifest.

Scripts

Scripts are key value pairs, intended to work similar to scripts of Node's package.json.

Declared scripts are listed by elide project (and surfaced in elide project advice).

For example, if you specify in script

scripts {
  ["help"] = "elide --help"
}

Note: elide run does not currently execute a script by name — the first non-option argument to elide run is always resolved as a source file path. Running a script by its manifest name is not yet supported.

Dependencies

Elide comes with a built-in, polyglot dependency manager. A single dependencies { } block declares packages across three ecosystems — npm (JavaScript/TypeScript), PyPI (Python), and Maven (JVM) — and one elide install resolves and installs them all. See Dependencies for the full installer guide.

import "elide:Jvm.pkl" as Jvm

dependencies {
  npm {
    packages { "react@19.0.0" }
  }
  pypi {
    packages { "six==1.17.0" }
  }
  maven {
    packages { "com.google.guava:guava:33.4.8-jre" }
  }
}

There are three ways to declare a Maven dependency:

import "elide:Jvm.pkl" as Jvm  

dependencies {
  maven {
    packages {
      // Coordinate string — the most common form
      "com.google.guava:guava:33.4.8-jre",
      // Structural form — use when you need to set a classifier or other fields
      new Jvm.MavenPackageSpec {
        group = "com.google.guava"
        name = "guava"
        version = "33.4.8-jre"
      }
      // Local JAR path — bypasses Maven resolution entirely (see below)
      "./libs/my-library.jar"
    }
  }
}

Maven dependencies are installed in your local Maven repository and linked into your project through .dev file.

Spring Boot starters

Spring Boot starters all share the coordinate shape org.springframework.boot:spring-boot-starter-, so a spring { } block lets you declare just the name and the Boot version:

dependencies {
  spring {
    version = "3.5.0"

    starter {
      "actuator"
      "web"
    }

    testStarter {
      "test"
    }
  }
}

dependencies {
  maven {
    packages {
      "org.springframework.boot:spring-boot-starter-actuator:3.5.0"
      "org.springframework.boot:spring-boot-starter-web:3.5.0"
    }
    testPackages {
      "org.springframework.boot:spring-boot-starter-test:3.5.0"
    }
  }
}

Only artifacts that follow the starter convention can be declared this way. Anything else — spring-boot-devtools, or artifacts in the org.springframework group — is declared as an ordinary coordinate in maven, and the two blocks merge:

dependencies {
  spring {
    version = "3.5.0"
    starter { "web" }
  }
  maven {
    packages {
      "org.springframework.boot:spring-boot-devtools:3.5.0"
      "org.springframework:spring-core:6.2.0"
    }
  }
}

Local JAR dependencies

Any dependency bucket (packages, modules, compileOnly, runtimeOnly, processors, kotlinPlugins, testPackages) accepts a local JAR file path in place of Maven coordinates. Path-based entries are read directly from disk.

import "elide:Jvm.pkl" as Jvm

dependencies {
  maven {
    packages {
      // Shorthand: any string that isn't a coordinate is treated as a path
      "./libs/my-library.jar"
      // Local JAR dependencies are declared as path strings (structural MavenPackageSpec entries are for coordinates only)
    }
    // Local JARs work in every bucket
    compileOnly {
      "./libs/annotation-processor.jar"
    }
    testPackages {
      "./libs/test-helpers.jar"
    }
  }
}

Relative paths are resolved from the project directory (the directory containing elide.pkl). Absolute paths are used as-is.

import "elide:Jvm.pkl" as Jvm 

dependencies {
  maven {
    repositories {
      ["central"] = new Jvm.MavenRepositorySpec {
        name = "Maven Central"
        description = "The central Maven repository"
        url = "https:<<>>
      }
      ["google"] = "https://maven.google.com"
    }
  }
}

Or specify a local repository and connect to maven central

dependencies {
  maven {
    localRepository = ".m2/repository"
  }
}

The complete dependency schema, including npm and PyPI fields, is listed in elide.pkl Reference.

JVM

Elide has a mechanism that allows for high level of configuration of how Elide interacts with the JVM.

In order to start configuring the JVM, you have to import the JVM-specific schema.

import "elide:Jvm.pkl" as Jvm
jvm {
  # your configuration here
}

At the high-level, you can specify what JVM you want elide to target and specify and entry point for your JVM.

jvm {
  main = "test.class"
  target = "latest"
  javaHome = "home"
}

Kotlin

Elide allows to configure Kotlin behavior.

kotlin {
  # your configuration here
}

plugins {
  ["plugin"] = {
    ["setting"] = "value",
  }
}

JavaScript

Elide allows to configure JavaScript ECMA level for the project.

javascript {
  ecma = "latest"
}

Native Image

Elide accepts a project-wide nativeImage { } block. Note: this block is currently parsed but not applied by the build — set Native Image options per artifact, in the artifact's options { } block (see the Native Image artifact below). The schema below documents the block's shape.

In order to start configuring the native compiler, you have to import a specific schema.

import "elide:NativeImage.pkl" as NativeImage

nativeImage {
  # your configuration here
}

Engine

This configuration is responsible for configuration of the execution engine used by Elide when running a project.

engine {
  # your configuration here
}

Dev

Dev configurations allow Elide to integrate fully into a development process of a project.

In order to start configuring dev settings, you have to import a specific schema.

import "elide:Dev.pkl" as Dev

dev {
  # dev configuration here
}

resources {
      new Dev.McpResource {
        # some resource config
      }
    }

Toolchain

Toolchain settings let you configure which Elide engine version to use.

toolchain {
  engines {
    ["elide"] = ">1.0.0"
  }
}

Artifacts

Elide can produce a variety of artifacts that can be placed into your project. These are declared as key-value pairs inside artifact configuration.

artifacts {
  ["some-artifact"] = {
    # some artifact
  }
}

import "elide:Jvm.pkl" as Jvm

artifacts {
  ["some-jar"] = new Jvm.Jar {
    # some config here
  }
}

Web

import "elide:Web.pkl" as Web

web {
  css {
    targets {
        new Web.CssTarget {
          # some config
        }
    }
  }
}

Elide Lockfile

Elide lockfile contains information about project metadata as well as a resolved dependency graph. It allows for faster elide build as unmodified dependency list will be skipped and resolved dependency graph will be used