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 https://clojurescript.org/community/building
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
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
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 https://github.com/clojure/clojurescript-site/blob/quick-start-1.10/content/guides/quick-start.adoc
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.
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.
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.
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.
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.
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.
However, when using shadow-cljs this is simply not true.
It looks like Mike Fikes is working on improving npm integration, likely as part of his Clojurists Together work over the next few months.
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:
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
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.
Is this why I’m getting
-bash: clj: command not found
because I am on 1.8?