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 ClojureScript - Building the compiler
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:
- 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 clojurescript-site/content/guides/quick-start.adoc at quick-start-1.10 · clojure/clojurescript-site · GitHub
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…
1 Like
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>?
2 Likes
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.
Hi David,
I’m completely new to ClojureScript, but I have been playing around with Clojure basics so I’m familiar with the basic syntax and idioms of the language.
I found the new quick start really helpful. It’s the first ClojureScript tutorial I had ever done. Nice that it introduces how to make use of React, too! I’m on a Mac, so it’s good not to have to manually download the jar file.
Thank you!
2 Likes
I had the same issue, then I realized that I was running the compilation command from the wrong location 
. It worked when I ran it in the same directory as the deps.edn file.
2 Likes
As a windows user, i had no problems with the QuickStart - until the “Dependencies” part.
I am not able to find any information on how to add the react dependency on windows, or any info if it is possible at the moment.
Thanks for all the hard work. I enjoyed it so far and can not wait to try figwheel-main.
1 Like
I’ve just been reading through the quick start, and it looks a lot better than when I started using Clojurescript a few year back.
I was wondering whether it is worth putting in something about shadow-cljs.
For me personally, Clojurescript before using shadow-cljs was really frustrating, as I constantly had to struggle to use other JavaScript libraries, hoping that someone had wrapped it with cljsjs.
However, since I discovered shadow-cljs, Clojurescript has gone from an interesting tool to the most important part of my programming toolbox.
The easy integration with the npm ecosystem is a killer feature, and one that I think should be marketed right from the beginning, even in the quickstart.
It is also something that I keep hearing from other developers checking out clojurescript - it looks interesting, but too difficult to integrate with the rest of the JavaScript world.
However, when using shadow-cljs this is simply not true.
If you plan to grow Clojurescript to the audience of JavaScript developers, I think you need to push this angle more.
6 Likes
It looks like Mike Fikes is working on improving npm integration, likely as part of his Clojurists Together work over the next few months.
See: https://twitter.com/mfikes/status/998249143507210240 and https://gist.github.com/mfikes/e6673df98da49b8a87ffadbf3dea8cf4
I wouldn’t be at all surprised if CLJS improved to the point that shadow-cljs was no longer needed for painless npm interop. But even if it doesn’t, I don’t think it’s appropriate for the Quick Start to point people to shadow-cljs. By the same token, a JavaScript Quick Start shouldn’t bother with WebPack, Gulp, Node, or JQuery — people will find these related tools as they begin to specialize their usage of the language. They will learn about these things “just in time”, rather than “just in case”.
1 Like
It would be cool if npm integration was improved, but the current situation is different.
I’m not suggesting that the quickstart be changed to demonstrate shadow-cljs, simply that a section be added at the end - something like next steps.
This is similar to the clojure quick start, which mentions lein and boot:
https://clojure.org/guides/getting_started
1 Like
First para:
Note that the requirement of a web browser excludes headless environments, and we then recommend skimming to the Node.js portion of the tutorial.
That’s jargony (“headless”) and the “, and” clause doesn’t make sense. Also, that sentence is in the wrong place since, whether you’re headless or not, you’ll need the file layout described in the very next section in order to use the Node section.
I recommend moving this instruction lower, say, right after the listing for hello-world.core e.g.
In running the guide, I must admit that I first made a core.clj instead of a core.cljs (habit). That caused the namespace to not be found when compiling. The correction, of course, was to rename the source file. Might be worth a little highlighting for those of us coming from Clojure JVM, who might not be paying attention.
The bigger issue I ran into was that (require '[hello-world.core :as hello] :reload) does not seem to dynamically compile-and-reload the namespace. I had to exit the REPL (via ^d) and then --compile from the terminal in order to see new definitions e.g. average.
1 Like
Is this why I’m getting
-bash: clj: command not found
because I am on 1.8?