Discussion: global exports convention

[martinklepsch]

Some packages already provide global exports (e.g. React) in the case of React the global exports namespace is just react.

I was wondering if there should be any additional namespacing, e.g. cljsjs.ge.react or whatever. Using just cljsjs.react probably isn't possible due to conflicts with the foreign lib stuff.

I think in combination with @honzabrecka's recent https://github.com/honzabrecka/ts-to-goog/ adventures we might be able to add a boat load of new libraries to cljsjs, properly and uniformly embracing the new global exports stuff would be great for this.

[honzabrecka]

I'll try to describe my thoughts on this topic.

Ts-to-goog takes an advantage from already existing TypeScript's ecosystem. It means that every single package with "typings" (written in TypeScript or providing TypeScript definition file) published on npm should be convertible and therefore reused in ClojureScript ecosystem. This is crucial as it differs from how cljsjs currently works.

Cljsjs packages provides both :externs and :foreign-libs, where both files require manual maintenance. It's completely separated from npm, which means that when the new version of npm package is published, cljsjs package is out of date and there's no automated mechanism to update it.

Also even though that the user who wants to update may reuse :externs from that outdated package, :foreign-libs may be something not-so-easy to update as it requires compilation on user's environment.

This point became invalid with recent version of ClojureScript that brings :npm-deps. As it can consume npm modules directly, there's no need for :foreign-libs in cljsjs packages, which means that update is quite easy.

This is exactly how DefinitelyTyped is designed. To use a library you have to install both packages, one for library and second for types.

Here's my suggestion:

• Cljsjs packages generated from TypeScript defs would contain just :externs.
• Those packages should have ts namespace in its name, eg. cljsjs.ts.react
• We can build a service that would periodically check for new releases on npm and convert&publish them automatically to clojars to remove any redundant manual work.

Hope it's clear.

[honzabrecka]

For the versioning I would suggest the following:

@types/[email protected] -> [cljsjs.ts.react "16.0.2-0"] where number after dash is important as it depends on combination of typescript & tsickle which have been used for the conversion.

[Deraen]

@honzabrecka It should be [cljsjs.ts/react "16.0.2-0"], we don't want to create a new group for each package.

Anyway, externs are not really related to global-exports, so we could open separate issue to discuss how to handle extern-only packages and externs from TS defs.

[martinklepsch]

I was thinking extern-only packages would use npm-deps but actually npm-deps and global exports are solving two distinct problems, right?

With that in mind I guess I'm proposing to automatically create packages that depend on npm-deps and using TS externs. If we create these packages we could drastically expand the list of available packages and people could easily ultilize the new npm deps feature, resulting in more bug reports & a better ClojureScript compiler.

[Deraen]

Most of Node modules won't need externs. Only special cases like React will need them. I'd have extern only packages only provide externs, without npm-deps.

[Deraen]

I wrote some docs about naming convention and global-exports: https://github.com/cljsjs/packages/wiki/Unified-module-names-and-global-exports

Naming convention and global-exports are separate, and either could be implemented without other. But both are needed to be able to use foreign-libs and Node modules interchangeably from libs.

[branch14]

New link for the doc on global exports:

https://github.com/cljsjs/packages/wiki/Npm-style-names-and-global-exports