Workspace

The workspace directory is the place where all our code and most of the configuration lives.
Let’s start by creating the example workspace with the top namespace se.example by using the create workspace command (create w works as well as create workspace). Make sure you execute the command outside a git repository:
poly create workspace name:example top-ns:se.example :commit
This will create a workspace in the main branch. By giving branch:BRANCH-NAME the workspace can be created in a different branch, e.g.:
poly create workspace name:example top-ns:se.example branch:master :commit
Note: In version 0.2.13-alpha and earlier, the workspace was automatically initiated as a git repository when we created a workspace, but from 0.2.14-alpha and later, we have to pass in :commit to get the same behaviour. We will talk more about this in the Git section.
The workspace directory structure will end up like this:
example            # workspace dir
├── .git           # git repository dir
├── bases          # bases dir
├── components     # components dir
├── deps.edn       # development config file
├── development
│   └── src        # development specific code
├── logo.png       # polylith logo
├── projects       # projects dir
├── readme.md      # documentation
└── workspace.edn  # workspace config file
The directory structure is designed for quick navigation and ease of use. It helps us to understand and find all our service-level building blocks, which lets us reason about the system at a higher level.
Each top-level directory contains a specific type of Polylith concept. A base is a building block that exposes a public API to external systems. A component is a building block for encapsulating a specific domain or part of the system. A project specifies our deployable artifacts and what components, bases, and libraries they contain. Finally, we have the development project (development + deps.edn) that we use to work with the code in one place.
This structure gives a consistent shape to all Polylith projects and ensures that both new developers and veterans can quickly understand and start working with systems that are new to them. We think you will soon be addicted to the power and simplicity the Polylith structure gives to your projects!
The bases, components and projects directories also contain a .keep file, which is added to prevent git from deleting these directories, and can be removed as soon as we add something to them.
The workspace.edn file looks like this:
{:top-namespace "se.example"
 :interface-ns "interface"
 :default-profile-name "default"
 :compact-views #{}
 :vcs {:name "git"
       :auto-add false}
 :tag-patterns {:stable "stable-*"
                :release "v[0-9]*"}
 :projects {"development" {:alias "dev"}}}
...and deps.edn like this:
{:aliases  {:dev {:extra-paths ["development/src"]
                  :extra-deps {org.clojure/clojure {:mvn/version "1.11.1"}}}
​
            :test {:extra-paths []}
​
            :poly {:main-opts ["-m" "polylith.clj.core.poly-cli.core"]
                   :extra-deps {polyfy/polylith
                                {:git/url   "https://github.com/polyfy/polylith"
                                 :sha       "a1581ccc87009127f2151579b826258dd57e3077"
                                 :deps/root "projects/poly"}}}}}
Note: Version 0.2.14-alpha contains a bug which adds a space in "1.10.1" that you need to remove manually!
If all went well, the poly tool managed to set the latest sha for the :poly alias by taking it from the master branch in this repository. We can instruct it to go and get it by passing in :latest-sha:
cd example
poly ws get:settings:vcs:polylith :latest-sha
The output will look something like this:
{:branch "master",
 :latest-sha "887e4237cec8f42eaa15be3501f134732602bb41",
 :repo "https://github.com/polyfy/polylith.git"}
The :latest-sha argument will tell the tool to go out and find the latest SHA from the Polylith repo and populate the :latest-sha attribute, which would otherwise not be set.
If you wonder how the ws command works or what all the settings are for, be patient, everything will soon be covered in detail.
Existing git repository
A polylith workspace can also be created inside an existing git repo. When we do that, we have two alternatives. Either we create the workspace directly at the root of the git repository by executing e.g.:
cd my-git-repo-dir
poly create workspace top-ns:com.mycompany
my-git-repo-dir
├── bases
├── components
├── deps.edn
├── development
├── projects
└── workspace.edn
...or we put the workspace in a directory under the git repository by executing e.g.:
cd my-git-repo-dir
poly create workspace name:my-workspace top-ns:com.mycompany
my-git-repo-dir
└── my-workspace
    ├── bases
    ├── components
    ├── deps.edn
    ├── development
    ├── projects
    └── workspace.edn
To execute a command, we need to be at the root of the workspace, e.g.:
cd my-workspace
poly info
​
Last modified 1mo ago