Question About Statement In Manual regarding :source-paths

[hammad-awan]

In the manual, it says the following:

"It is not recommended to separate source files by extension (eg. src/clj, src/cljs, src/cljc). For some reason this is widely used in CLJS project templates but it just makes things harder to use."

But it does not explain the reasoning behind it. As a n00b Clojure developer who is trying to get up to speed on using some of the various build tools which is a little bit overwhelming, I would like to know why. I have looked at Luminus the template structures its created projects in this way. How else would a proposed project with client, server, and shared code be structured in a project that only uses shadow-cljs?

Regards.

[thheller]

Well, it is my subjective opinion so YMMV. Template authors do many things that I don't necessarily agree with but that doesn't mean its wrong. I'll likely just remove that sentence entirely but let me expand on it a little bit.

Clojure and ClojureScript are both namespaced systems so I recommend keeping things sorted by namespace. I much prefer to have a directory structure like

.
└── src
    └── main
        └── my
            └── project
                ├── server
                │   ├── db.clj
                │   └── web.clj
                ├── server.clj
                ├── shared.cljc
                └── ui
                    ├── components
                    │   └── foo.cljs
                    ├── main.cljs
                    ├── some_macros.clj
                    └── some_macros.cljs

As opposed to strictly following the rules of split paths and separating them further creating an unnecessary complex directory structure.

└── src
    ├── clj
    │  └── my
    │       └── project
    │           ├── server
    │           │   ├── db.clj
    │           │   └── web.clj
    │           ├── server.clj
    │           └── ui
    │               └── some_macros.clj
    ├── cljs
    │   └── my
    │       └── project
    │           └── ui
    │               ├── components
    │               │   └── foo.cljs
    │               ├── main.cljs
    │               └── some_macros.cljs
    └── cljc
        └── my
            └── project
                └── shared.cljc

Again this is entirely subjective and doing it another way is not wrong. Pick a style you like and stick with it.

[hammad-awan]

Thanks for the response. I was actually thinking along the same lines as you (except I thought of "server", "client" and "shared") but being noob I was unsure of what the "other" or another way should be.

A couple of quick questions. Does the "main" folder serve any particular purpose? Is it because there could be another "test" folder at that level? Also, how would say a company name fit in the folder structure to namespace? I've seen that remarked upon elsewhere.

Regards.

[thheller]

I commonly have src/main for the main application/library code, then src/dev for development time only code and finally src/test for tests. Strictly speaking you do not need that separation either and could just put everything into src. However this separation helps when packaging code as either a library or for production. There you usually only want to include the files in src/main and ignore the others.

[thheller]

Regarding namespaces it helps to understand the classpath. I attempted to explain that in this blog post.

It is common convention in the JVM ecosystem (which Clojure is a part of) to use the reverse domain name notation. So company.com becomes com.company and then further grouped below that like com.company.project.ui.components etc. Clojure people (including me) are often not following that strictly so shadow-cljs code live in the shadow.cljs.* package as opposed to org.shadow-cljs.*

The only thing that matters is that the names are unique enough to not conflict with other code from your dependencies or other libraries. I always advise to avoid generic name such as app.ui because of the potential conflicts although even that is arguably not necessary.