# poly: the command line tool behind Polylith in Clojure > poly is the Clojure and ClojureScript tool for the Polylith architecture, a workspace where service level building blocks live in one place and can be assembled into different deployable artefacts. The README is unusually short for a tool of this ambition, so most of what you need comes from the cljdoc documentation. **polyfy/polylith** — A tool used to develop Polylith based architectures in Clojure. - Repository: https://github.com/polyfy/polylith - Website: https://cljdoc.org/d/polylith/clj-poly - Stars: 613 · Forks: 57 - Language: Clojure - License: EPL-1.0 - Published: 2026-10-22 · Updated: 2026-10-22 · Language: en - Canonical page: https://hysenlabs.com/projects/polyfy-polylith ## Not a build tool, but it plugs into the build The README makes a distinction that matters before anything else. Polylith is not a build tool, it integrates into your build pipeline. The tool described here is the poly command line tool, built for Clojure and ClojureScript, and the goals stated are to decrease complexity, maximize productivity and make coding a more joyful experience. The claims are about architecture rather than tooling, which is the point. Polylith introduces the architectural concept of service level building blocks that can be combined like LEGO bricks to build services and systems, and the README argues those bricks are easy to reason about, test, refactor and reuse because all the code lives in one place, reachable from a single REPL. Read that as the actual value proposition. You are not buying a faster compiler, you are buying a layout for your source tree, and poly is the tool that keeps that layout honest. ## The vocabulary: interface, component, base, brick, project, workspace The README points at the Polylith concept documentation before the tool documentation, and the reason is that the tool's commands only make sense once the nouns do. The concepts introduced there are interface, component, base, brick, project and workspace, and the gitbook page called Polylith in a Nutshell is the recommended minimum reading. A brick is a service level building block, a project is a deployable artefact assembled from bricks, and the workspace is the single place the code lives. The Clojure implementation of these ideas shows up in the repository layout, with directories named bases/, components/ and projects/, a deps.edn for the dependency manifest, a workspace.edn describing the workspace itself and a build.clj for the build tasks. The names are consistent across the concept and the code, which is the sign of a well executed idea. ## One REPL, many deployable artefacts The architectural payoff is described with the LEGO comparison, and the comparison is more precise than it first appears. In the same way bricks are assembled into different shapes, the bricks in a Polylith workspace can be assembled into different kinds of deployable artefact, such as services and tools, from the same source tree. That is the difference from a conventional multi-module build, where a shared library is a module and an application is another module, and the modules drift apart because each application is free to depend on a different slice of the shared code. Here every component is a first class citizen with a namespace you can load in a REPL, and the artefacts are assembled on top. The README points to a single REPL for maximum productivity, and for Clojure and ClojureScript specifically that means the same source can feed a JVM service and a JavaScript-targeting dialect. ## The examples directory is a list of things that go wrong The repository has an examples/ directory, and the names of its subdirectories are the most informative part of the tree. You get disable-validations and disable-warnings, which are configuration switches, and then a run of deliberately broken setups: illegal-brick-deps, illegal-configs, inconsistent-libs, local-dep and local-dep-old-format, missing-component, transitive-lib-deps and mix-example. There are also test-oriented ones, for-test, test-runners and profiles, and a local-maven-repo case, plus a poly-rcf directory. Read as a test corpus, they enumerate the failure modes the tool is built to detect: a component depending on something it should not, a configuration that is not allowed, a library version that disagrees with the workspace, a missing component, a dependency that arrives transitively when it should be direct. A tool that ships fixtures for its own error cases is a tool that expects to be integrated into a build pipeline and to fail loudly. ## Clojure and ClojureScript, one workspace, two targets The tool serves both Clojure and ClojureScript, and the README spells out the pairing in plain terms. Clojure is described as a powerful and simple functional language for the JVM, and ClojureScript as its JavaScript-targeting dialect. Since the building blocks are shared, a component written once can serve a server side service and a browser side application, which is the same argument the LEaGO assembly makes about deployables but applied to runtime targets. The tooling around the workspace reflects a working Clojure setup rather than a minimal one. There is a deps.edn and a build.clj side by side, a bb.edn for Babashka tasks, a .clj-kondo directory for the linter configuration, a .circleci directory for continuous integration, a scripts/ directory, a development/ directory and a doc/ directory with the images the README embeds, plus examples/ and next-release.md for the release notes of the next version. ## An EPL tool with cljdoc docs and a small release rhythm The licence is EPL 1.0, which is the Eclipse Public License, a copyleft scheme that fits a tool distributed as a library for others' build pipelines. The documentation lives outside the repository on cljdoc, with the README pointing at the current documentation URL, and the badges in the README are generated from a stable version and a snapshot version, which is the cljdoc convention for publishing a SNAPSHOT of the next release alongside the last stable one. The release history shows steady, small increments, with 0.3.33 on 2026-09-13 and a 0.3.34-SNAPSHOT on 2026-09-16, and 0.3.32 back in December 2025. The last push was on 2026-09-16, and the project is not archived. Communication is through a Slack channel listed in the README, and the project asks for sponsorship, listing sponsor tiers and the people who support it, which is a reasonable sign for a tool whose maintenance is concentrated in a few hands. ## Conclusion Adopt poly if you write Clojure or ClojureScript and you want to keep a large system in one workspace with one REPL, reassembling the same building blocks into different deployable artefacts as services or tools. Do not adopt it if your project is small, because the workspace structure and the tooling around it only pay off once there are many bricks, and expect to read the external documentation rather than the README. Verify first that your workspace really separates bases, components and projects in the way Polylith expects, and read the introduction in the cljdoc documentation and the Polylith in a Nutshell guide before you restructure an existing codebase, since the value here comes entirely from the architecture and the tool only enforces it. ## FAQ ### What is the poly tool for Clojure? It is the command line tool for developing Polylith based architectures in Clojure and ClojureScript. Polylith introduces service level building blocks that can be assembled into different deployable artefacts, and poly keeps the workspace in that shape. ### Is Polylith a build tool? The README says explicitly that Polylith is not a build tool but integrates into your build pipeline. The goals are architectural, to decrease complexity, maximize productivity and work with all the code in one place from a single REPL. ### What is a Polylith workspace made of? The repository layout shows bases/, components/ and projects/ directories, alongside deps.edn, workspace.edn and build.clj. The concepts behind those names are interface, component, base, brick, project and workspace, which the README asks you to read about in the Polylith in a Nutshell guide before the tool documentation. ### What do the examples in the poly repository cover? The examples directory includes deliberately broken setups used to exercise the tool's checks, such as illegal-brick-deps, illegal-configs, inconsistent-libs, local-dep, missing-component and transitive-lib-deps, along with configuration examples for disabling validations and warnings, profiles and test runners. ### Where is the poly documentation and how is it released? The documentation is published on cljdoc, with the README linking the current version, and the project publishes a SNAPSHOT alongside the last stable release. Versions include 0.3.33 on 2026-09-13 with a 0.3.34-SNAPSHOT following, and the project is licensed under EPL 1.0. ## Sources - [License: EPL-1.0](https://github.com/polyfy/polylith/blob/master/LICENSE) - [polyfy/polylith on GitHub](https://github.com/polyfy/polylith) - [Project website](https://cljdoc.org/d/polylith/clj-poly) - [README](https://github.com/polyfy/polylith/blob/master/README.md) - [Releases](https://github.com/polyfy/polylith/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/polyfy-polylith