Configuration

Table of Contents

Poly workspace.edn
- Projects
Tools.deps deps.edn Files
Poly User config.edn
Custom configuration

We have three categories of configuration:

Category File(s) Workspace Structure :configs key(s)

Category	File(s)	Workspace Structure `:configs` key(s)
`poly` workspace	`workspace.edn`	`:workspaces`
tools.deps	`deps.edn` files in projects and bricks	`:projects` `:bases` `:components`
`poly` user	`~/.config/polylith/config.edn`	`:user`

poly workspace

workspace.edn

:workspaces

tools.deps

deps.edn files in projects and bricks

:projects :bases :components

poly user

~/.config/polylith/config.edn

:user

If you are following along from our example workspace tutorial, you might notice some output does not exactly match what we show here. In some cases, we added a bit of config just to show what it would look like.

Poly `workspace.edn`

An initial workspace.edn is automatically generated when you create a workspace. You make changes by editing the workspace.edn file directly.

You can list workspace configs with the ws command:

poly ws get:configs:workspaces (1)

1	The `poly` tool will only return one workspace. The argument is the plural `workspaces` because we have plans to support returning mulitple workspaces someday.

[{:config { ... }
  :name "example"
  :type "workspace"}]

Key Description

Key	Description
`:config`	The content of `workspace.edn`
`:name`	(derived) The workspace’s name (defined by its directory)
`:type`	(derived) Always `"workspace"`

:config

The content of workspace.edn

:name

(derived) The workspace’s name (defined by its directory)

:type

(derived) Always "workspace"

You can retrieve the :config for a specific workspace via, e.g.:

poly ws get:configs:workspaces:example:config

{:bricks {"user-remote" {:keep-lib-versions [ring/ring slacker/slacker]}}
 :compact-views #{},
 :default-profile-name "default",
 :interface-ns "interface",
 :projects {"command-line" {:alias "cl",
                            :test {:setup-fn project.command-line.test-setup/setup,
                                   :teardown-fn project.command-line.test-setup/teardown}},
            "development" {:alias "dev"},
            "user-service" {:alias "user-s"}},
 :tag-patterns {:release "v[0-9]*", :stable "stable-*"},
 :top-namespace "se.example",
 :vcs {:auto-add true, :name "git"}}

The workspace map keys are:

Key Description

Key	Description
`:bricks`	Brick-specific configuration where the map key is the brick name. Specify `:keep-lib-versions` to tell `libs :update` to skip specified libraries. Default: absent, effectively `{}`
`:compact-view`	Can tell `poly` to use a compact format for deps command output and libs command output. For example, to turn compact format on for both `deps` and `libs`, set to `#{"deps" "libs"}`. Default: `#{}`
`:default-profile-name`	The name of the profile that `poly` automatically merges into the development project when using profiles, and no profile is specified. Default: `"default"`
`:interface-ns`	Tells `poly` when to consider a namespace an interface and what naming convention the create component command should use. See Interface for important details. Default: `"interface"`
`:projects`	See projects below. Default: see below
`:tag-patterns`	Specifies the regex patterns used when searching for the most recent tag in git. As explained in Tagging, `poly` uses this pattern to calculate the latest committed sha that is considered the latest stable point in time. Default: `{:stable "stable-" :release "v[0-9]"}`
`:top-namespace`	The top namespace used throughout the workspace in components and bases, specified by you when you create your workspace. Default: none, must be specified
`:vcs`	A map with two keys describing your version control system: `:name` at this time, always `"git"` `:auto-add` a boolean, when `true`, tells `poly` to automatically add directories and files to git that are generated by the create command. Default: `{:name "git" :auto-add false}`

:bricks

Brick-specific configuration where the map key is the brick name. Specify :keep-lib-versions to tell libs :update to skip specified libraries.
Default: absent, effectively {}

:compact-view

Can tell poly to use a compact format for deps command output and libs command output. For example, to turn compact format on for both deps and libs, set to #{"deps" "libs"}.
Default: #{}

:default-profile-name

The name of the profile that poly automatically merges into the development project when using profiles, and no profile is specified.
Default: "default"

:interface-ns

Tells poly when to consider a namespace an interface and what naming convention the create component command should use. See Interface for important details.
Default: "interface"

:projects

See projects below.
Default: see below

:tag-patterns

Specifies the regex patterns used when searching for the most recent tag in git. As explained in Tagging, poly uses this pattern to calculate the latest committed sha that is considered the latest stable point in time.
Default: {:stable "stable-*" :release "v[0-9]*"}

:top-namespace

The top namespace used throughout the workspace in components and bases, specified by you when you create your workspace.
Default: none, must be specified

:vcs

A map with two keys describing your version control system:

:name at this time, always "git"
:auto-add a boolean, when true, tells poly to automatically add directories and files to git that are generated by the create command.

Default: {:name "git" :auto-add false}

Projects

You configure individual projects under the :projects key. You can retrieve projects config via:

poly ws get:configs:workspaces:example:config:projects

{"command-line" {:alias "cl",
                 :test {:setup-fn project.command-line.test-setup/setup,
                        :teardown-fn project.command-line.test-setup/teardown}},
 "development" {:alias "dev"},
 "user-service" {:alias "user-s"
                 :test {:exclude ["mybrick"]}
                 :keep-lib-versions [org.slf4j/slf4j-nop]
                 :necessary ["helper"]}}

The keys are the full project names.

The default alias for the development project is created for you when your create your workspace. Deployable projects get no automatically generated config under :projects.

Project map keys are:

Key Description

Key	Description
`:alias`	Specifies a short name for a project. You can use the alias instead of the full project name for various `poly` commands. If not specified, the info and libs commands emit a `?` followed by a number (e.g. `?1`) for project column headings.
`:keep-lib-versions`	Tells `libs :update` to skip specified libraries for the project.
`:necessary`	Supports turning off `Warning 207` for one or more bricks. See Validations.
`:test`	See next table below.

:alias

Specifies a short name for a project. You can use the alias instead of the full project name for various poly commands. If not specified, the info and libs commands emit a ? followed by a number (e.g. ?1) for project column headings.

:keep-lib-versions

Tells libs :update to skip specified libraries for the project.

:necessary

Supports turning off Warning 207 for one or more bricks. See Validations.

:test

See next table below.

You specify test configuration under the :test key for a specific project:

Key Description

Key	Description
`:exclude`	Lists the bricks to exclude when running tests for the project. ¹
`:include`	Lists the bricks to include when running tests for the project. ¹
`:setup-fn`	The function name (including namespace) to call before `poly` runs tests. ²
`:teardown-fn`	The function name (including namespace) to call after `poly` runs tests. ²

:exclude

Lists the bricks to exclude when running tests for the project. ¹

:include

Lists the bricks to include when running tests for the project. ¹

:setup-fn

The function name (including namespace) to call before poly runs tests. ²

:teardown-fn

The function name (including namespace) to call after poly runs tests. ²

Table notes:

See Include and Exclude Bricks by Configuration.
See Test Setup and Teardown.

Tools.deps `deps.edn` Files

The various poly create commands create initial deps.edn files. You make changes via manual edits or the libs :update command.

Projects

Each project has its own deps.edn configuration file.

You’ll find:

The development project config in ./deps.edn. The create workspace command creates the initial file.
Deployable projects are configured in projects/PROJECT-DIR/deps.edn where PROJECT-DIR is the deployable project’s directory (and name). The create project command creates the initial file.

You can retrieve a project’s tools.deps config via, e.g.:

poly ws get:configs:projects:command-line

{:deps {:aliases {:test {:extra-deps {}, :extra-paths ["test"]},
                  :uberjar {:main se.example.cli.core}},
        :deps {org.apache.logging.log4j/log4j-core {:mvn/version "2.13.3"},
               org.apache.logging.log4j/log4j-slf4j-impl {:mvn/version "2.13.3"},
               org.clojure/clojure {:mvn/version "1.11.1"},
               poly/cli {:local/root "../../bases/cli"},
               poly/user-remote {:local/root "../../components/user-remote"}}},
 :name "command-line",
 :type "project"}

Key Description

Key	Description
`:deps`	Content of project `deps.edn`
`:name`	(derived) The project name
`:type`	(derived) Always `"project"` for projects

:deps

Content of project deps.edn

:name

(derived) The project name

:type

(derived) Always "project" for projects

Bases

Each base tools.deps config is found in bases/BASE-DIR/deps.edn where BASE-DIR is the base’s directory (and name). The create base command creates the initial file.

You can retrieve a base’s tools.deps config via, e.g.:

poly ws get:configs:bases:cli

{:deps {:aliases {:test {:extra-deps {}, :extra-paths ["test"]}},
        :deps {},
        :paths ["src" "resources"]},
 :name "cli",
 :type "base"}

Key Description

Key	Description
`:deps`	Content of base `deps.edn`.
`:name`	(derived) The base name.
`:type`	(derived) Always `"base"` for bases.

:deps

Content of base deps.edn.

:name

(derived) The base name.

:type

(derived) Always "base" for bases.

Components

Each component tools.deps config is found in components/COMPONENT-DIR/deps.edn where COMPONENT-DIR is the component’s directory (and name).

You can retrieve a component’s tools.deps config via, e.g.:

poly ws get:configs:components:user

{:deps {:aliases {:test {:extra-deps {}, :extra-paths ["test"]}},
        :deps {},
        :paths ["src" "resources"]},
 :name "user",
 :type "component"}

Key Description

Key	Description
`:deps`	The content of `deps.edn`.
`:name`	(derived) The component name.
`:type`	(derived) Always `"component"` for components.

:deps

The content of deps.edn.

:name

(derived) The component name.

:type

(derived) Always "component" for components.

Poly User `config.edn`

You specify your user preferences in ~/.config/polylith/config.edn. If it does not already exist, the create workspace automatically creates this file for you.

If you started using the poly tool from version 0.2.14-alpha or earlier, then the settings may be stored in ~/.polylith/config.edn:

You can retrieve the config via:

poly ws get:configs:user

{:color-mode "dark", :empty-character ".", :thousand-separator ","}

Key Description

Key	Description
`:color-mode`	Valid values are `"none"`, `"light"` and `"dark"`; see the Colors. You can override when running `poly` commands with e.g.: `poly info color-mode:none`. Default: `"none"` on Windows, `"dark"` on other operating systems.
`:empty-character`	The `poly` tool uses this character in output for the deps and libs commands. Default: `"."`
`:thousand-separator`	The thousands separator for `:loc` for the info command. Default: `","`
`:m2-dir`	Tells the libs where it can find your local Maven repository, which it uses to calculate library `KB` sizes. Default: `~/.m2`

:color-mode

Valid values are "none", "light" and "dark"; see the Colors. You can override when running poly commands with e.g.: poly info color-mode:none.
Default: "none" on Windows, "dark" on other operating systems.

:empty-character

The poly tool uses this character in output for the deps and libs commands.
Default: "."

:thousand-separator

The thousands separator for :loc for the info command.
Default: ","

:m2-dir

Tells the libs where it can find your local Maven repository, which it uses to calculate library KB sizes.
Default: ~/.m2

Custom configuration

If you have custom configuration data, then we suggest that you put it in a :custom key in workspace.edn at the root and/or under each brick/project. If you put your custom data there, it will not collide with future keys introduced by the tool.

❮Libraries Validations❯