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:
1
poly create workspace name:example top-ns:se.example
Copied!
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.:
1
poly create workspace name:example top-ns:se.example branch:master
Copied!
The workspace directory structure will end up like this:
1
example            # workspace dir
2
├── .git           # git repository dir
3
├── bases          # bases dir
4
├── components     # components dir
5
├── deps.edn       # development config file
6
├── development
7
│   └── src        # development specific code
8
├── logo.png       # polylith logo
9
├── projects       # projects dir
10
├── readme.md      # documentation
11
└── workspace.edn  # workspace config file
Copied!
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. A workspace is always initialized to use git, but more on that later.
The workspace.edn file looks like this:
1
{:top-namespace "se.example"
2
 :interface-ns "interface"
3
 :default-profile-name "default"
4
 :compact-views #{}
5
 :vcs {:name "git"
6
       :auto-add false}
7
 :tag-patterns {:stable "stable-*"
8
                :release "v[0-9]*"}
9
 :projects {"development" {:alias "dev"}}}
Copied!
...and deps.edn like this:
1
{:aliases  {:dev {:extra-paths ["development/src"]
2
                  :extra-deps {org.clojure/clojure {:mvn/version "1.10.1"}
3
                               org.clojure/tools.deps.alpha {:mvn/version "0.12.1003"}}}
4
​
5
            :test {:extra-paths []}
6
​
7
            :poly {:main-opts ["-m" "polylith.clj.core.poly-cli.core"]
8
                   :extra-deps {polyfy/polylith
9
                                {:git/url   "https://github.com/polyfy/polylith"
10
                                 :sha       "ecd2cf2ede81ecd4fbf82f21a075b103b6f2d2af"
11
                                 :deps/root "projects/poly"}}}}}
Copied!
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:
1
cd example
2
poly ws get:settings:vcs:polylith :latest-sha
Copied!
The output will look something like this:
1
{:branch "master",
2
 :latest-sha "887e4237cec8f42eaa15be3501f134732602bb41",
3
 :repo "https://github.com/polyfy/polylith.git"}
Copied!
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.:
1
cd my-git-repo-dir
2
poly create workspace top-ns:com.mycompany
Copied!
1
my-git-repo-dir
2
├── bases
3
├── components
4
├── deps.edn
5
├── development
6
├── projects
7
└── workspace.edn
Copied!
...or we put the workspace in a directory under the git repository by executing e.g.:
1
cd my-git-repo-dir
2
poly create workspace name:my-workspace top-ns:com.mycompany
Copied!
1
my-git-repo-dir
2
└── my-workspace
3
    ├── bases
4
    ├── components
5
    ├── deps.edn
6
    ├── development
7
    ├── projects
8
    └── workspace.edn
Copied!
To execute a command, we need to be at the root of the workspace, e.g.:
1
cd my-workspace
2
poly info
Copied!
​
Example - Previous
Example systems
Next - Architecture
Development
Last modified 1mo ago
Copy link