62e0a7c3222e791d40a3e46a8e6ac1a7ab22118d
GaiwanStack/ClojureConventions.md
... | ... | @@ -0,0 +1,24 @@ |
1 | +# Gaiwan's Clojure Conventions |
|
2 | + |
|
3 | +## Project Structure |
|
4 | + |
|
5 | +- We use Clojure CLI / `deps.edn` |
|
6 | +- `src` is for source files, Clojure and ClojureScript or cljc |
|
7 | +- The main namespace has at least two segments, an org name and a project name, so `src/org_name/project_name.clj` |
|
8 | +- Optionally but recommended, use a reverse domain name for the org name, so you get a (at least) 3-segment name, e.g. `co.gaiwan.our-app` |
|
9 | +- This main namespace has a `-main` function that uses [lambdaisland/cli](https://github.com/lambdaisland/cli) |
|
10 | +- Other namespaces in the project are prefixed with the org+project name, e.g. `co.gaiwan.our-app.some-ns`, in other words all other source files go under `src/org_name/project_name/` |
|
11 | +- The following will refer to `org-name.project-name` as `prefix` |
|
12 | +- `resources` is for non-source files that should be accessible on the classpath |
|
13 | +- Avoid having files directly inside `resources`, especially with generic names (`config.edn`, `index.html`), because they could easily conflict with other stuff on the classpath. Use `prefix` instead, e.g. `resources/org_name/project_name/config.edn` |
|
14 | +- `prefix.config` requires `com.lambdaisland.config`, loads the config, sets the `prefix`, and exposes it to the rest of the app by wrapping the access functions |
|
15 | +- Config follows the conventions as described in the [lambdaisland/config](https://github.com/lambdaisland/config) README |
|
16 | + |
|
17 | +## Tooling |
|
18 | + |
|
19 | +- We use babashka scripts where applicable |
|
20 | +- `bb.edn` should include launchpad and/or lambdaisland/cli |
|
21 | +- `bin/dev` is where we create dev tasks, it's a bb script using li/cli |
|
22 | +- `bin/launchpad` is a [[WellKnownIdentifier]] that starts launchpad |
|
23 | +- `bin/kaocha` is a [[WellKnownIdentifier]] that runs tests |
|
24 | +- `*.local.*` and `*.local` are gitignored (`deps.local.edn`, `config.local.edn`, `.env.local`, etc) |