ClojureScript 1.10.X - New Quick Start, Feedback please :)



Include instructions on how to build clojurescript itself. especially how you build it for release I thought it would be a simple as lein uberjar but I’m not sure


It’s not appropriate for the Quick Start but we have those instructions on website now, see


I just started going through this today and noticed a few things that I believe might add friction for early and beginner ClojureScript developers

1. Comment on where to run clj

We show a new user the expected file structure. It could be helpful for us to tell them to cd hello-world and run in the root of that directory.

2. Comment on src dir in the Hello, ClojureScript Section

There are a few implicit details that might be odd for newcomers. For example, if you do not put your hello_world/core.cljs into the src directory, running clj --main cljs.main --compile hello-world.core --repl from within the hello-world dir is not going to run successfully and will give you an Exception in thread "main" java.lang.IllegalArgumentException: Namespace test does not exist error message.

My rationale for the above is that there are some unique qualities that developers from other languages, think Python, or JS, would find odd in CLJ/S:

  1. namespaces v file paths

we do hello-world.core where as in other languages compiling a file in the terminal would just write something like node src/hello-world/core.js and more interestingly (which you did note, so that is awesome) the kebab case further throws people off the trail. Especially if not from a Java world.

So because the quickstart kind of skips over them, could be odd. I agree that we should not spend time talking about them here, just a comment re-enforcing that they are important.

Hope this helps!


Might be worth adding that this needs clojure 1.9 to work. 1.8 is the most recent version on macports. I know the install recommends using brew, but some of us still prefer to use port and may get bitten by this.


This is covered in the very first part of the Quick Start and we state that it’s important. Do you have something more direct that you would like to see?

It’s a Quick Start and we’re making very deliberate choices about what environments we cover. Other popular tools make similar narrowing decision in their documentation, it just makes for better reading and a better experience for more users.


I believe this is the part you were referring to?

First set up a project folder for our Hello World program. Here’s a 
list of the files and folders you’ll need. Note  that the underscores 
in the names are important.

My suggestion would be to add something to the end of it like

Further, your hello_world/core.cljs must be inside of the `src` directory for 
the CLI tool to find your code."


The very first thing we say is that you must establish a specific directory structure with a diagram which shows exactly where to put everything. Are you skipping this part?


I don’t think I am. I see that it says First set up a project folder for our Hello World program. and then the comment of here are the exact files and folders you will need. but I still think it is worth adding something to the effect of what I mentioned.

Unless I am indeed missing something? I am referencing this version of the quick start


I hear you. I didn’t mean support another environment, just suggesting a change of “an installation of clojure” to “an installation of clojure 1.9+”. Makes it slightly more idiot proof…


For me, a major road-block in any Getting Started guide is being asked to manually set up the directory/file structure for the project, or cloning a random github project.

I haven’t used clj at all, but isn’t there something like clj new <template> <project>?


Out of scope for what we plan to do. But thanks for the feedback.


Hmm. If you don’t mind me asking: Why? It looks like the guide covers some ‘clj’ stuff already.