Source code — polylith/clj-poly 0.2.18

Source code

Paths

In all our examples thus far, we’ve shown source code stored in two directories: src and test. Tools.deps supports splitting source and test code into several directories, as does poly.

We’ve only shown .clj files in our examples, but poly also recognizes .cljc files, which you can use to share code between Clojure and ClojureScript. (See Frontend Code Options below.)

We’ll contrive an example of splitting source code over multiple directories by exploring two ways of storing .clj and .cljc files. Imagine a company component that contains both .clj and .cljc files. You can choose to store both types of files in the same src directory:

├── components
│   ├── company
│   │   ├── src

For this strategy, you’d configure the component’s deps.edn file like so:

{:paths ["src"]
 ....

An alternative is to store the source code in two separate directories:

├── components
│   ├── company
│   │   ├── clj
│   │   ├── cljc

And configure :paths in the component’s deps.edn file as:

{:paths ["clj" "cljc"]
 ....

Some prefer this scheme, as it clearly shows where all the .cljc code resides. We are not recommending one strategy over the other. Our focus is to illustrate splitting source code over multiple paths.

Resources

The resources directory stores non-source files, e.g., images or data, and lives in bricks and, optionally, projects. To keep resource paths unique on the classpath, poly creates a sub-directory under resources when creating a brick. For components, the sub-directory name is the component’s interface name, and for bases, it’s the base name, e.g.:

├── bases
│   ├── worker
│   │   ├── resources
│   │   │   └── worker
│   │   │       └── mydata.edn
├── components
│   ├── creator
│   │   ├── resources
│   │   │   └── creator (1)
│   │   │       └── logo.png

1	By default, the interface names match component names

If you have resource files that are only used in the test context, then they can be put in a test-resources directory.

Frontend Code Options

The poly tool doesn’t understand ClojureScript .cljs files, but it recognizes .cljc files, which you can use to share code between your backend and frontend.

Three frontend code organization alternatives are:

1. Frontend in Base or Components

This option puts all your frontend code in a base.

The poly tool recognizes .cljc files in the base, resulting in a ClojureScript view of the component when used from the frontend.

If you want to share the .cljc code with the backend, you would put that code in one or more components.

2. Frontend in a Non-`poly` Directory

Another option is to put the frontend code in a separate directory. Two alternatives are:

a) Under the Workspace

myworkspace
├── bases
├── components
├── development
├── myfrontend (1)
└── projects

1	Not a base, not a component, just your frontend code referenced as `:local/root`

You would include .cljc files from your backend code by treating it as a library and referencing it via :local/root. A drawback is that changes to the frontend code files will not be detected by poly because they sit outside the poly directory structure and are, therefore, unknown to poly.

We are currently discussing how to properly recognize and support ClojureScript within a poly workspace.

b) Outside the Workspace

Under this strategy, the frontend code sits within your git repository but physically outside of the workspace.

myrepository
├── mybackend (1)
│   ├── bases
│   ├── components
│   ├── development
│   └── projects
└── myfrontend (2)

1	mybackend `poly` workspace
2	myfrontend plain old Clojure `:local/root` library

You would reference frontend .cljc files as a :local/root library in the same way as in alternative 2a. The poly tool can handle both layouts; it’s more a matter of preference what you choose.

3. Frontend in Separate Repository

The last alternative is to put your frontend code in a separate git repository.

Some downsides to this strategy are:

You are no longer working with a monorepo and might even have separate frontend and backend releases
You have a greater risk of the frontend and backend code becoming out of synch