Understand Clojure Project Structure

Clojure project structure is lighter than a typical Java application, but it is not structureless. The important difference is that Clojure organizes runtime code around namespaces and classpath roots rather than classes under package directories.

The Minimal Shape

A small Clojure CLI project usually starts like this:

 1hello-world/
 2├── deps.edn
 3├── resources/
 4│   └── logback.xml
 5├── src/
 6│   └── hello_world/
 7│       └── core.clj
 8└── test/
 9    └── hello_world/
10        └── core_test.clj

Namespace to File Mapping

Most Clojure source files declare one namespace at the top:

1(ns hello-world.core)

That namespace belongs in:

1src/hello_world/core.clj

The mapping is mechanical:

    flowchart LR
	    A["Namespace hello-world.core"] --> B["Classpath root src/"]
	    B --> C["Directory hello_world/"]
	    C --> D["File core.clj"]

This matters because Clojure loads namespaces from the JVM classpath. If the namespace and file path disagree, the error often looks like a classpath problem even when the real problem is naming.

Source and Test Namespaces

A source namespace:

1(ns hello-world.core)
2
3(defn greeting [name]
4  (str "Hello, " name "!"))

A matching test namespace:

1(ns hello-world.core-test
2  (:require [clojure.test :refer [deftest is testing]]
3            [hello-world.core :as core]))
4
5(deftest greeting-test
6  (testing "builds a greeting"
7    (is (= "Hello, Ada!" (core/greeting "Ada")))))

The -test suffix is a convention, not a JVM requirement. It makes test discovery and human navigation easier.

deps.edn Structure

A practical first deps.edn might look like this:

1{:paths ["src" "resources"]
2 :deps {org.clojure/clojure {:mvn/version "1.12.4"}}
3 :aliases
4 {:test {:extra-paths ["test"]}
5  :run {:main-opts ["-m" "hello-world.core"]}}}

For a Java engineer, the main shift is that paths are explicit classpath roots. Test code is not automatically visible unless you include it through an alias or tool-specific convention.

Leiningen Project Structure

A Leiningen project has a similar source layout but uses project.clj:

1hello-world/
2├── project.clj
3├── resources/
4├── src/
5│   └── hello_world/
6│       └── core.clj
7└── test/
8    └── hello_world/
9        └── core_test.clj

The practical difference is ownership:

Learn both layouts enough to read an existing repository. Pick one default only when creating a new project.

Common Structure Mistakes

Key Takeaways

• Clojure projects are organized around classpath roots and namespaces.
• Namespace names map predictably to file paths.
• Test namespaces should mirror source namespaces, but test paths must be included deliberately.
• deps.edn and project.clj are both project configuration files; do not mix them casually in one small project.
• Keep the first project small enough that namespace and classpath mistakes are easy to see.

Quiz: Project Structure