Libraries section

The Libraries section lets you develop a shared library locally and see it in the micros that consume it, without publishing it to a registry. Aseptic builds its artifact and links it into each consumer. It supports npm, Maven, Gradle and Python libraries.

It’s a section with a list + detail pattern (like Micros): on the side, the library catalog; in the center, the editable detail of the selected one.

What “linking” means

It depends on the technology, because each ecosystem resolves its dependencies somewhere different. You don’t pick the mechanism: Aseptic picks it from what the library is.

Technology	Where the artifact ends up	What unlink undoes
npm	copied over the consumer’s `node_modules/<package>`	removes the copy and restores the original folder
Maven and Gradle	the local repository (`~/.m2`), where every consumer resolves from	removes that version from the local repository (Maven downloads it again from the remote)
Python	the wheel (`.whl`), installed into each consumer’s virtual environment	uninstalls it and reinstalls whatever version was there before

All three are reversible: every link leaves a marker, and unlinking only undoes what Aseptic put there. An artifact that was already there — a version downloaded from the registry — is never touched.

Add a library

From the add button (top bar) —also offered in the section’s empty background when there are none yet—:

Add library — you choose the repo’s folder. As soon as you do, Aseptic shows you what it recognised before adding anything: the technology, the package name, the version, and which micros in the catalog already declare it. If the folder isn’t a library it knows how to build, it says so right there and won’t let you continue.
Import from Git — clones the repo and adds it. There’s no preview here: there’s nothing on disk to look at until after cloning.

The technology is derived from the repo: pom.xml → Maven, build.gradle → Gradle, package.json with name → npm, pyproject.toml/setup.py → Python. The package is the name as whoever consumes it would write it: the name from package.json, groupId:artifactId on the JVM, the distribution name in Python.

A library’s detail

Identity and build recipe. It saves on its own (autosave with a small delay, like in Micros; it can be disabled in Settings):

Name and Package.
Technology — the one derived when it was added. You can change it if it got it wrong.

Build — the command that builds the artifact and the artifact path. If you don’t declare them, the profile of its technology is used:

Technology	Default build	Artifact path
npm	`npm run build`	`dist/<last segment of the package>`
Maven	`${mvn} install -DskipTests`	`target`
Gradle	`${gradle} publishToMavenLocal -x test`	`build/libs`
Python	`python -m build --wheel`	`dist`

Consumers — the micros that use the library. By default they are detected on their own by reading who declares that package (package.json, pom.xml, build.gradle, requirements.txt, pyproject.toml); you can fix them by hand (comma- separated micro ids).
Watch changes — automatically rebuilds and relinks when the code changes.

${mvn} and ${gradle} are replaced with the repo’s executable: its wrapper (mvnw, gradlew) if it ships one, the global one otherwise. That way the recipe works the same on every machine in the team.

Status and actions

Per library:

Action	What it does
Install	Installs the library’s dependencies in its repo (build and link do it on their own if they’re missing).
Build	Generates the artifact.
Link	Builds and puts the artifact where each consumer resolves it (see the table above).
Unlink	Undoes the link in each consumer and restores whatever was there before.
Watch	Does build + link hot on every change. Needs the live engine.

Each library’s status (built / not built, linked in N consumers, watching) is shown in the list and in the detail.

While watching, Aseptic ignores what the build itself writes — node_modules, target, build/, the virtual environment and the caches — so it doesn’t fall into an endless rebuild loop.

A note on Maven and Gradle

On the JVM the artifact does not live in the consumer’s repo, but in your local repository. That has two consequences:

The link applies to all micros at once, whether or not they’re in the scenario.
If your library doesn’t let its version be resolved from the repo (a pom.xml that inherits it via ${revision}, a group computed in a Gradle script), the link will tell you. Fix it by declaring the version in the library’s YAML (stack.version).

Repository (Git)

Like in Micros, a library’s detail includes its Git: switch branches, do fetch and pull (--ff-only). Access is read-only (never does push), and if there are uncommitted changes, Aseptic warns before switching branches or updating.

If the repo is not on disk

If a library’s folder moved, the detail marks it and offers to relocate: you choose the new folder and the path is saved.

Non-invasive

Aseptic does not modify the consumer’s repo or the library’s: it doesn’t touch their package.json, pom.xml or requirements.txt. What it touches is what lives outside Git — node_modules, the local repository, the virtual environment — and always with a marker so it can be reverted.

There’s one exception worth knowing about in npm: an npm install in the consumer wipes its node_modules and takes the link with it. Aseptic notices and links it again afterwards. With Maven and Gradle this doesn’t happen, because the artifact doesn’t live there.

Deleting a library from the catalog does not unlink it: if it was linked, unlink it first from the detail.

From the CLI and the MCP

aseptic library detect/list/status/build/link/unlink/watch. The read-only ones (library_detect, library_list, library_status) are also available as MCP tools.