Add details on deps.cljs

[jmlsf]

The deps.cljs file is discussed by example in a couple of places:

• https://clojurescript.org/reference/dependencies
• https://clojurescript.org/reference/packaging-foreign-deps
• https://cljs.github.io/news/0.0-2719

I'd really like to see a slightly more formal description of how this file works. Questions:

• Is the deps.cljs filename hardcoded?
• Does it only work inside jars? (Only at the top level directory?)
• Can there be more than one in a project? How do they interact if so?
• Can it contain anything other than a :foreign-libs key?

(I think part of my confusion lies from the fact that I'm a bit fuzzy on the mechanics of what happens when you add a dependency string to a lein project file. I always thought that the dependency strings only affected the downloading of dependencies to disk--not compiler options. I think the answer is that the dependency vector downloads the jars to disk and the presence of a deps.cljs file on disk affects the compiler, but it'd be great to have this spelled out.)

CC: @johnmn3

[johnmn3]

More info:

Other optional keys include :externs and :npm-deps.

:npm-deps also allows for 'upstream' deps.cljs files.

See more info here: https://github.com/clojure/clojurescript/commit/21da03e03e229a0b38fb872485d26a30fbf034b8

[swannodette]

I think we probably need a new guide about developing ClojureScript libraries. However I would like any such guide to give recommendations aligned with :target :bundle.

[cap10morgan]

@swannodette How do you envision :target :bundle libraries working when consumed by another :target :bundle project? It seems like there needs to be a way to tell the downstream consumer project how to compile the library; and those compilation instructions should land in the library's JAR? Or just look for build.edn and use that? Or should the :target :bundle tooling auto-generate a deps.cljs for downstream consumers to use? Something else entirely?

[swannodette]

There's nothing more to do it, as what you're talking about is already supported. You can transitively depend on some CLJS lib that depends on node modules and it will work.

[cap10morgan]

@swannodette Oh interesting! I must be doing something wrong then because the transitive npm deps in my library aren’t found when a consuming project tries to build its CLJS. Both are :target :bundle based.

[swannodette]

You need declare those :npm-deps, put them in deps.cljs and this file needs to be at the root of the classpath of the project that you're going to depend on. Pretty sure there's a blogpost in the wild now about these details that you can maybe Google for. We definitely need to update the official docs.

[cap10morgan]

@swannodette Ah, OK. I think I’ve read the blog post in question. I was hoping for a solution where I didn’t need to redundantly specify my npm deps (which are already in package.json for :target :bundle).

I’m also hoping to avoid having two different approaches to specifying npm deps in libraries vs. apps. I’d like to just use :target :bundle everywhere. And it feels really close to just working if the library consumers could be told how to build the library too.

I just had a conversation about this in the clojurescript channel in Clojurians Slack if you’d like to take this out of this issue. Thanks for your help!

[henryw374]

This is my blog post on the topic: http://widdindustries.com/cljs-npm-libraries/

I can submit the text as a PR if you might use it?