Skip to content

Dependencies

Declare Maven, npm and PyPI dependencies in elide.pkl and install Maven and npm packages with elide install: ecosystems, options and installed files.

Read offlineelide help tooling-dependencies

On this page

Declare dependencies in elide.pkl and install them with elide install.

Ecosystem Enable with Read from
Maven default elide.pkl, or a pom.xml project selected with -p
npm --ecosystems=npm elide.pkl and package.json
PyPI — dependencies.pypi is accepted; elide install does not install it

Install dependencies

Terminal
bash
elide install                         # Maven
elide install --ecosystems=npm        # npm
elide install --ecosystems=maven,npm  # both
elide install --workspace             # every ecosystem the project declares
Installing Maven and npm dependencies explicitly with Elide
 ~/demo  elide install --ecosystems=npm,maven
[722ms] ✓ NPM packages installed (541ms)
[18.1s] ✓ Resolved 17 Maven dependencies (17.4s)
[18.1s] ✓ Dependencies installed in 18.0s
 ~/demo  elide install --ecosystems=npm,maven
[ 11ms] Already up to date
[ 17ms] ⇥ Dependencies ready (Up to date)
[ 22ms] ✓ Dependencies installed in 13ms
 


A package.json does not turn on npm; name every ecosystem CI needs. An unknown or unavailable ecosystem is a usage error.

What elide install doeselide install reads the dependencies in elide.pkl, or pom.xml with -p. With --fresh, or when the dependency list changed, it resolves the full graph from the repositories, downloads in parallel with checksums verified, and checks or pins each artifact's SHA-256. When the list is unchanged it downloads only files missing from disk, or is already up to date. Artifacts are linked from .dev/dependencies/m2 beside the classpath files. npm, when named, installs into .dev/dependencies/npm with aube-lock.yaml.yesnoyesno--ecosystems=npmelide installRead elide.pkl,or pom.xml with-p--fresh, or thelist changed?Resolve the graphfrom therepositoriesDownload inparallel,checksumsverifiedCheck or pineach SHA-256Files missing?Up to dateLink the Mavencache,write classpathsnpm install,aube-lock.yaml

Maven resolution is reused while the dependency list is unchanged: a missing file is restored on its own, and every artifact’s SHA-256 is pinned the first time it is seen and checked after that.

elide install --fresh resolves the graph again and downloads every required non-provided artifact again, bypassing local artifact caches, worktree borrowing and HTTP conditional reuse. No additional --no-cache flag is needed. It verifies the required artifacts without first deleting the installed repository. A failed refresh leaves existing files in place. Matching JARs bundled with Elide are installed locally rather than downloaded: hard links avoid extra copies where supported, with copying as a fallback. JARs borrowed from mutable local repositories are copied into the project. Both remain usable after the source distribution or cache is removed. --direct always requests copies. Installation fails if a required artifact or provided resource is unreadable. Refresh does not prune unused cached artifacts; the resolved graph and written classpaths determine which dependencies are used.

The committed binary lockfile also keeps a compact portable graph for immutable dependency versions. When the manifest, roots, classifier requirements and platform match, a new checkout can restore that graph instead of analyzing POMs again. Artifact SHA-256 pins remain stable across machines; distribution-provided bytes are checked against the current distribution rather than pinned across Elide versions. Snapshots and open version selectors require resolution rather than portable-graph reuse. Invalid or incompatible integrity lockfiles fail installation rather than silently resetting pins. Concurrent saves merge independent pins and reject conflicting hashes.

In a Git worktree, missing pinned releases may be copied from neighboring worktrees, starting with the closest commit history, including the main checkout. Copied bytes must match this project’s lockfile before publication. Other checkouts are read-only sources, their unpinned extras are not imported, and the current distribution supplies its own JARs. A legacy shared dependency-directory link is migrated to a private copy before installation. Warm installs with complete verified files do not scan neighboring worktrees. --fresh does not borrow artifacts or reuse non-provided releases, even when their bytes match the lockfile hash.

Declare dependencies

pkl
amends "elide:project.pkl"

dependencies {
  maven {
    packages {
      "com.google.guava:guava:33.4.8-jre"
    }
  }
  npm {
    packages { "react@19.0.0" }
    devPackages { "typescript@5.6.2" }
  }
  pypi {
    packages { "requests>=2" }
    optionalPackages { ["dev"] { "pytest>=8" } }
  }
}
utf-8 · pkl · Lines: 17

For a project with only a pom.xml, run elide install -p .; see Maven Dependencies.

Maven buckets

An entry is group:artifact:version[:classifier], a MavenPackageSpec, a local JAR path, or a project("name") reference. Workspace members can omit the version and take the root’s (Workspaces), and an entry declared beside a BOM (group:bom:pom:version) can omit it and take the version the BOM lists. Conflicts resolve nearest-first, as in Maven, unless overridden by resolutions.

Bucket Applies to
packages Compile and runtime classpaths of production sets.
devPackages Development time only.
modules --module-path for compiles, runs, tests and native images.
compileOnly Compile classpath only.
runtimeOnly Runtime classpath only.
processors Annotation-processor path; see Maven Dependencies.
testPackages Test sets, in addition to their production set’s dependencies.
androidTestPackages The androidTest source set: Android instrumented tests, which run on a device; never the host’s test classpath.
kotlinPlugins Kotlin compiler plugins; see Kotlin Compiler.
exclusions Removed from resolution and every classpath.
substitutions Local files replacing a coordinate on every classpath; see reference.

Maven version resolutions

Use resolutions to select an exact version wherever a module appears in the dependency graph:

pkl
dependencies {
  maven {
    resolutions {
      ["org.example:library"] = "1.2.3"
    }
  }
}
utf-8 · pkl · Lines: 7

Keys are group:artifact; the override applies to direct and transitive requests, including all classifiers and packaging types, before their POMs are fetched. It does not add a dependency or restore an excluded dependency. Version ranges, wildcards, LATEST and RELEASE are rejected. Workspace members inherit root resolutions and can override them by key. Changing or removing a resolution causes the dependency graph to be resolved again.

Spring Boot starters:

pkl
dependencies {
  spring {
    version = "4.0.0"
    starter { "web"; "actuator" }
    testStarter { "test" }
  }
}
utf-8 · pkl · Lines: 7

Each name becomes org.springframework.boot:spring-boot-starter-<name>:<version> in packages or testPackages. Other Spring artifacts (spring-boot-devtools, org.springframework:*) go in maven; the two merge. The Spring Boot guide shows a complete manifest for building, testing and packaging an application with Elide.

Android libraries, by family:

pkl
dependencies {
  android {
    androidx { ["activity-compose"] = "1.9.3"; ["core-ktx"] = "1.15.0" }
    compose { bom = "2025.10.00"; modules { "ui"; "foundation"; "material3"; "ui-tooling" } }
    material = "1.12.0"
    playServices { ["location"] = "21.3.0" }
    test { runner = "1.6.2"; modules { "ext-junit" }; espresso { "core" } }
    robolectric = "4.16"
  }
}
utf-8 · pkl · Lines: 10
Family Becomes
androidx androidx.<group>:<artifact>: core-ktx is androidx.core:core-ktx; a nested group leads with its segments, wear-compose-material3 is androidx.wear.compose:compose-material3.
compose androidx.compose.<group>:<module>, versioned by the BOM (bom) or at one release (version).
material com.google.android.material:material.
playServices com.google.android.gms:play-services-<name>.
test androidx.test:runner and the named AndroidX Test and Espresso libraries, at the release of runner, in androidTestPackages.
robolectric org.robolectric:robolectric and the JUnit vintage engine elide test needs, in testPackages.

A name its family does not know fails evaluation, naming the family and the name. Anything else goes in maven; the two merge. Android archives need no aar packaging: it is read from the library’s published metadata. See Android dependencies.

Repositories

pkl
dependencies {
  maven {
    repositories {
      ["company"] = "https://maven.example.com/releases"
      ["private"] {
        url = "https://packages.example.com/maven"
        credentials {
          username = read("env:MAVEN_USER")
          password = read("env:MAVEN_TOKEN")
        }
      }
    }
    localRepository = ".m2/repository"
  }
}
utf-8 · pkl · Lines: 15
Property Meaning
repositories[name].url Repository URL.
repositories[name].credentials.username, .password Basic authentication.
repositories[name].credentials.ntlmDomain, .ntlmWorkstation Either one selects NTLM.
repositories[name].name, .description Display name and description.
enableDefaultRepositories Include Maven Central (default true).
localRepository Local Maven repository to resolve into.
  • Plain http:// to anything but 127.0.0.0/8 fails with Maven repository 'name' uses plain HTTP. elide build deps --allow-http-repositories accepts it.
  • read("env:…") needs --allow-env; see Build Flags.
  • With enableDefaultRepositories, Maven artifacts come from the maven.pkg.st proxy first, then Maven Central. A project declaring android or dependencies.android also resolves against Google’s Maven repository: recognized public Google URLs try gmaven.pkg.st first, then their original endpoint. Custom mirrors and authenticated repositories keep their existing routes. pkg.st is enabled by default. elide --no-pkgst build deps or ELIDE_PKGST=false disables automatic proxy routing and every pkg.st feature below. Explicit global flags override the environment. The build-specific --use-pkgst=false (or --no-use-pkgst) also disables Maven’s pkg.st features; it cannot override the global opt-out. Explicitly configured repository URLs remain in use, with ordinary Maven transport.
  • Release POMs from maven.pkg.st and gmaven.pkg.st can arrive dictionary-compressed (RFC 9842 dcz) when the distribution ships the pinned Maven POM dictionary; Elide checks each decoded POM against the SHA-256 that pkg.st reports, and falls back to gzip or plain XML otherwise. elide build deps --no-pkgst-dictionary or ELIDE_PKGST_DICTIONARY=false turns this off. ELIDE_PKGST_MAVEN_ORIGINS (comma-separated origins, such as a staging mirror) extends the same negotiation beyond the built-in Central and Google Maven pkg.st origins. Google POMs use canonical XML; the current compact-descriptor client targets Maven Central’s namespace only.
  • pkg.st names the POMs a response leads to (parents, imported BOMs, direct dependencies), and Elide fetches them ahead of resolution within fixed item, byte and concurrency budgets. elide build deps --pkgst-prefetch (or ELIDE_PKGST_PREFETCH=1 for elide install) also follows the parent and imported BOM POMs each downloaded POM declares; that is off by default.
  • Each dependency’s JAR starts downloading as soon as resolution reaches it, instead of after the whole graph is known. ELIDE_PKGST_EARLY_ARTIFACTS=0 waits for the graph.
  • A JAR from pkg.st larger than 32 MB (64 MB once the link measures fast) downloads as parallel byte ranges, joined in order and checked against the SHA-256 pkg.st reports. ELIDE_PKGST_RANGES=0 downloads each JAR as one response.
  • Descriptor mode defaults to auto: Elide fetches POMs’ declared models from pkg.st as compact descriptors ahead of resolution over a WebSocket per worker (wss://pkg.st/v1/descriptors:stream), compressed with a Zstandard dictionary Elide ships, through the same proxy and TLS settings as other Maven requests. If the stream is unavailable, the rest of the run uses batches multiplexed over HTTP/2 with Brotli, Zstandard or gzip bodies; --pkgst-descriptors=http uses only those. A POM resolution needs before its descriptor has arrived is fetched as XML. Usable workspace and local POMs still take precedence, and a POM pkg.st cannot describe is fetched as XML and checked against its SHA-256.
  • Fetched descriptors are kept in .meta/pkgst-descriptors/ and reused on later runs; --fresh fetches them again. Keep that directory alongside the Maven repository when reusing CI caches.
  • --pkgst-descriptors=cached reuses descriptors already on disk and never requests one. --no-pkgst-descriptors or ELIDE_PKGST_DESCRIPTORS=off uses XML only. ELIDE_PKGST_DESCRIPTORS takes the same values, and an explicit command-line mode wins over it.
  • A repository’s prefix catalog (.meta/prefixes.txt) from pkg.st is requested as a delta against the copy Elide already holds, or the copy it ships with: a few hundred bytes instead of the full catalog.
  • When a file is already in the local repository during an ordinary install, Elide can send its SHA-256 and MD5 as If-None-Match. An unchanged file answers 304 and is kept; a changed or damaged one is downloaded again. --fresh omits these conditional validators and downloads the artifact body again.
  • After an install, a two-line Maven cache report shows an efficiency meter and hits out of known cacheable fetches, followed by transfer savings, origin offload and local reuse. Wider terminals also show POM, JAR and metadata meters. --verbose retains the full breakdown with separate POM, artifact and other metadata rows. Successful GETs qualify when the response shows a cache hit or a usable cache lifetime; uncacheable responses, probes, unknown policies and failed requests are shown outside that denominator. Zero eligible fetches show n/a, not 100%. A local 304 saves client bytes but is not itself proof that the server avoided its upstream. Origin offload estimates describe known cacheable body bytes; unknown sizes are counted separately. Client savings show compression, local revalidation and descriptor replacement against identity-equivalent bytes, separately from local resolved-file reuse. These byte savings are estimates, and the report covers Maven rather than npm or Python traffic. --quiet omits it. The same breakdown is exported over OTLP: elide.install.cache.eligible.requests separates hits, misses, exclusions, unknown policy and failures by file kind; elide.install.cache.eligible_hit_ratio uses only known cacheable fetches. Byte counters separate origin offload from client transfer savings. The older overall response-hit metrics remain available for compatibility and use a different denominator.
  • Maven metadata activity shares one progress row. Archive fetches take priority once downloads begin; auxiliary completion redraws are coalesced by the terminal ticker to avoid repainting for every POM.
  • With telemetry configured, installs export aggregate resolution spans and a bounded sample of request detail. Successful pkg.st requests use the server’s spans; client failures and retries have a separate detail budget. Later requests retain unsampled correlation context. Repository 404 probes are counted separately from genuine failures; a required dependency missing everywhere still fails the install. Decode and filesystem/hash processing times appear in the final correlated report, alongside bytes, caching and latency. Trace context (traceparent, baggage) is sent to pkg.st only. The final summary log and an optional aggregate transport diagnostic use the same configured OTLP pipeline; there are no per-probe logs.
  • The Maven lockfile records the supplying repository for downloaded artifacts, without URL credentials or local filesystem paths. Repair and additional-classifier downloads prefer that supplier among your currently configured repositories, retaining upstream fallbacks and honoring --no-pkgst. Repository hints never add new endpoints or bypass SHA-256 verification. Existing locks remain readable and acquire hints as artifacts are resolved again.
  • If pkg.st’s descriptor service does not answer within five seconds, the run continues with XML. Maven still applies inheritance, interpolation, profiles, management and relocation to every model.

elide build deps runs the same resolution as a task and also takes --offline, --allow-http-repositories, --use-pkgst, --pkgst-dictionary, --pkgst-prefetch and --pkgst-descriptors.

Installed files

Path Contents
.dev/dependencies/npm/node_modules npm packages; node_modules at the project root links here.
aube-lock.yaml npm lockfile.
.dev/dependencies/m2 Links into the standard Maven cache.
.dev/dependencies/m2/{compile,runtime,test,processors}.classpath Resolved classpaths; see elide classpath.

In a workspace, links are in the root’s .dev/dependencies/; classpath files stay per project. There is no cross-ecosystem lockfile; see Build state.

Query dependency code

The experimental dependency code index records types, members, and references from resolved Maven JARs. Build it with elide index build --layers=l1,l2,l3, then use resolve to find which artifact defines a class, get to inspect a type or member, and references to follow its code references. used-by finds matching compiled local sources.

OpenRewrite uses the same index for Java source transformations. Add recipe modules to devPackages; they are development tools, separate from application dependencies.

Implicit JVM libraries

  • Java-only roots get no implicit Kotlin libraries, Metro runtime or Elide annotation API, even with a kotlin block.
  • Kotlin roots get the libraries their kotlin.features enable.
  • Kotlin roots also get the atomicfu runtime unless kotlin.features.atomicfu = false.
  • Test sets get bundled JUnit unless jvm.features.testing = false; elide test then needs your own junit-platform-console for JVM tests.
  • dev.elide:elide-api accepts latest as a version and resolves to the bundled artifact.
  • Bundled libraries link Elide’s own JARs, but their sources and Javadoc come from your repositories like any other dependency’s, so --with=sources attaches kotlin-stdlib sources too. elide-api has none.

The full list, with versions: JVM APIs. To use Elide annotations from Java:

pkl
dependencies {
  maven {
    compileOnly { "dev.elide:elide-api:1.0.0" }
  }
}
utf-8 · pkl · Lines: 5

npm specifics: NPM Installer.

Studio session defaults also apply to the embedded npm installer: ELIDE_PKGST=1 enables the package CDN unless explicitly overridden by CLI flags. Requests to the HTTPS npm.pkg.st origin carry a valid ELIDE_STUDIO_SESSION_ID for internal correlation. Other registries receive no Studio session header. The native installer retains unchanged package content when dependency versions drift; Elide’s .dev/dependencies/npm layout does not require an exact whole-project input match to reuse those packages.

Was this page helpful?