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
elide install # Maven
elide install --ecosystems=npm # npm
elide install --ecosystems=maven,npm # both
elide install --workspace # every ecosystem the project declares
~/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.
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
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" } }
}
}
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:
dependencies {
maven {
resolutions {
["org.example:library"] = "1.2.3"
}
}
}
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:
dependencies {
spring {
version = "4.0.0"
starter { "web"; "actuator" }
testStarter { "test" }
}
}
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:
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"
}
}
| Family | Becomes |
|---|---|
androidx |
androidx.: core-ktx is androidx.core:core-ktx; a nested group leads with its segments, wear-compose-material3 is androidx.. |
compose |
androidx., versioned by the BOM (bom) or at one release (version). |
material |
com.. |
playServices |
com.. |
test |
androidx.test:runner and the named AndroidX Test and Espresso libraries, at the release of runner, in androidTestPackages. |
robolectric |
org. 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
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"
}
}
| Property | Meaning |
|---|---|
repositories[name].url |
Repository URL. |
repositories[name]., .password |
Basic authentication. |
repositories[name]., .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 but127.0.0.0/8fails withMaven repository 'name' uses plain HTTP.elide build deps --allow-http-repositoriesaccepts it. read("env:…")needs--allow-env; see Build Flags.- With
enableDefaultRepositories, Maven artifacts come from themaven.pkg.stproxy first, then Maven Central. A project declaringandroidordependencies.androidalso resolves against Google’s Maven repository: recognized public Google URLs trygmaven.pkg.stfirst, then their original endpoint. Custom mirrors and authenticated repositories keep their existing routes. pkg.st is enabled by default.elide --no-pkgst build depsorELIDE_PKGST=falsedisables 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.standgmaven.pkg.stcan arrive dictionary-compressed (RFC 9842dcz) 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-dictionaryorELIDE_PKGST_DICTIONARY=falseturns 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(orELIDE_PKGST_PREFETCH=1forelide 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=0waits 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=0downloads 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=httpuses 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;--freshfetches them again. Keep that directory alongside the Maven repository when reusing CI caches. --pkgst-descriptors=cachedreuses descriptors already on disk and never requests one.--no-pkgst-descriptorsorELIDE_PKGST_DESCRIPTORS=offuses XML only.ELIDE_PKGST_DESCRIPTORStakes 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 answers304and is kept; a changed or damaged one is downloaded again.--freshomits 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.
--verboseretains 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 shown/a, not 100%. A local304saves 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.--quietomits it. The same breakdown is exported over OTLP:elide.install.cache.eligible.requestsseparates hits, misses, exclusions, unknown policy and failures by file kind;elide.install.cache.eligible_hit_ratiouses 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 |
|---|---|
. |
npm packages; node_modules at the project root links here. |
aube-lock.yaml |
npm lockfile. |
.dev/dependencies/m2 |
Links into the standard Maven cache. |
. |
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
kotlinblock. - Kotlin roots get the libraries their
kotlin.featuresenable. - Kotlin roots also get the atomicfu runtime unless
kotlin.features.atomicfu = false. - Test sets get bundled JUnit unless
jvm.features.testing = false;elide testthen needs your ownjunit-platform-consolefor JVM tests. dev.elide:elide-apiacceptslatestas 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=sourcesattacheskotlin-stdlibsources too.elide-apihas none.
The full list, with versions: JVM APIs. To use Elide annotations from Java:
dependencies {
maven {
compileOnly { "dev.elide:elide-api:1.0.0" }
}
}
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.