Bundling Isomorphic Components

[ryansolid]

I've been debating this for a while and now that I've gathered my thoughts I'd like to request some feedback from the community.

The question is:

Should Solid libraries be exporting precompiled code as you find in React or the direct JSX templates like you find in a library like Vue or Svelte?

Background

Solid is a hybrid solution of runtime and build time JavaScript. At build time we compile our JSX into optimal JavaScript. This JavaScript differs based on compiler settings. Are we outputting for client or for server? Is the output hydratable? Today we even support multiple types of SSR generation based on whether we want to use the reactive system on the server as well. If you are keeping track that's 6 different types of output before considering ES6 modules vs CJS.

Solid at runtime has different runtimes based on the environments too. We have our typical reactive client, and then the 2 different server models. These each have their own optimizations. This is a lot for a would-be third-party developer to consider.

Fortunately, there are some things in the works and there is some tooling that can help us here. I am in the process of combining the server bundles into a single compiled output and single runtime. However, this still at best leaves us with 3 different outputs at a minimum if we assume server-rendered is always hydratable. Secondly, conditional exports in package.json allow us to alias builds based on a keyword. I already use this to great effect with solid-js/web which depending will import different versions. browser and server keywords along with node allow us to select the right bundle based on the environment.

Any 3rd party library could use the same convention to ship different bundles. However, what I've done with solid-js/web is expose static isServer booleans so that smart bundlers like Rollup can automatically dead code eliminate any isServer code branches from our client bundles. So anything you need on first render only can be safely placed here and won't end up in your client bundle even if compiled from the same source. So it's possible that 3rd parties won't need to use special exports for the most part.

Shipping Source

The upside of shipping Source is that it is incredibly easy to author. Even TypeScript users only need to run tsc to output JS and types with jsx: preserve and they are done. You would still need to include the babel plugin for testing but JavaScript source could basically stay as is without any bundler or build step. It also doesn't tie your library to a version of the compiled output. JSX syntax changes a lot slower than compiled output. With the source things could continue to work across many versions without breaking.

The downside of shipping Source is that browser only environments can't handle it. The end user needs to tell their bundler to transpile node modules. With the exception of Parcel this is pretty easy to do. Unfortunately, Parcel is used by CodeSanbox one of the easiest ways to share code online. Reckless compilation of node_modules can also be problematic. This would never be a problem in prebuilt starters but might be the push to go that way. As in the perception being the tooling is too complicated.

{
  "type": "module",
  "export": {
    ".": {
      "node": "./dist/server.jsx",
      "default": "./dist/client.jsx"
    }
  }
}

Libraries like Svelte define their own path to source, so we could come up with a special export path to go that way but it would never be the default if someone just was getting started, unless we provided a bundler plugin for each of Rollup, Webpack, and Parcel, etc..

Shipping Compiled

For starters 3rd party authors would need to produce 3 outputs otherwise their library would not be supported in all envs. We'd need to set the hydratable client as a separate export in the package map. This means every author would need to build for each of the 3 setups times cjs vs esm. It's possible we could just make everything type module and only export esm but I don't know if there are other traps there.

So the upside is the packages would be easy consumable for end-users in the browser and we'd still just be using the prescribed conditional exports to pick our package version. The downside is every author would need to setup their builds in a specific way to have it work. And we'd need to introduce new export for the hydratable client.

{
  "type": "module",
  "export": {
    ".": {
      "hydrate": "./dist/hydrate.js",
      "node": {
        "import": "./dist/server.js",
        "require": "./dist/server.cjs"
      },
      "default": "./dist/client.js"
    }
  }
}

Hybrid?

I was thinking of this binary for the longest time which made me think that shipping source was the only really viable option. But we could ship the source under a special export and then build the source for the client only. So by default, it would work as a client library and then to do SSR it used the source via custom fields. This unfortunately includes client hydratable builds. So it wouldn't just work on client or server for SSR.

This still requires the 3rd party author to create the client build (at least if they want their stuff to run in the browser) but otherwise, they can ship with source. However, if they ever wanted to have different source between browser and server it's a bit trickier but they could use conditionals.

Simple source no difference with client server (ie.. uses isServer)

".": {
  "solid": "./dist/index.jsx",
  "default": "./dist/index.js",
}

Different server and client source

".": {
  "solid": {
     "node": "./dist/server.jsx",
     "default": "./dist/client.jsx"
   },
  "default": "./dist/index.js",
}

In any case, I'm looking for thoughts here. This is a tricky matter and a lot of recent discussions have been about what guarantees or lack of guarantees come from using exports and an overall concern of opening this up to be a wild west of things.

Further Reading:

• https://github.com/lukeed/resolve.exports
• https://twitter.com/_developit/status/1347296236282523648

[TheComputerM]

Don't know much about this and the new exports maps but can't you just ship jsx and a compiled js for browser only environments?

[ryansolid]

Yeah this is the hybrid approach. It means that when doing server rendering there is a bunch of extra config. But that is probably ok.

I actually think locking compiled output to a Solid version might actually be the bigger killer long term. But that also might be just because we are less stable. I feel like features tend to not just be runtime and affect both sides often enough though.

[amoutonbrady]

So, I’m kind of the instigator of the initial discussion but as you know, I was keen to try and propose a progressive enhancement to what the bundler expects. Here’s how I published my latest version of solid-utils. Essentially generating 3 files (4 if you count ts declarations):

• One in the CJS format (probably overkill but at least if a bundler tries to load CJS only it won’t break) via Rollup
• One in the ESM format via Rollup
• One in the JSX format via tsc.

The first two are compiled and meant for browser use only. This way, they can be consumed via CDN calls.

The latter one is rather a bet on future tooling. I do hope that bundler will more and more use the "source" key at the root of the ’package.json’ and apply the proper plugin as if this was a file you had locally.

This also is in the same spirit of providing one source file and being able to transform regarding of whether we are doing SSR or not.

Here’s what the relevant part of the ’package.json’ looks like:
Some export mapping is probably overkill as well like node/require.

  "source": "./dist/source/index.jsx",
  "main": "./dist/cjs/index.js",
  "module": "./dist/esm/index.js",
  "exports": {
    ".": {
      "solid": "./dist/source/index.jsx",
      "import": "./dist/esm/index.js",
      "node": "./dist/cjs/index.js",
      "require": "./dist/cjs/index.js",
      "browser": "./dist/esm/index.js"
    }
  },

[frenzzy]

@amoutonbrady your post led me to this idea:

  "source": "./src/index.tsx", // have no idea who may use it but looks cool :)
  "solid": "./dist/source/index.js", // or for solid compiler (shortcut, like main vs exports fields)
  "main": "./dist/server/cjs/index.js", // for legacy node runtime
  "module": "./dist/server/esm/index.js", // for legacy bundlers which makes SSR bundles
  "browser": { // overrides for browsers and legacy bundlers
    "./dist/server/cjs/index.js": "./dist/browser/cjs/index.js",
    "./dist/server/esm/index.js": "./dist/browser/esm/index.js",
  },
  "exports": { // for modern node and future bundlers
    ".": {
      "source": "./src/index.tsx", // have no idea who may use it but looks cool :)
      "solid": "./dist/source/index.js", // for solid compiler
      "node": {
        "require": "./dist/server/cjs/index.js", // for require in node
        "default": "./dist/server/esm/index.js" // for import in node
      },
      "require": "./dist/browser/cjs/index.js", // for require in browser and other possible environments
      "default": "./dist/browser/esm/index.js" // for import in browser and other possible environments
    }
  },
  "types": "./dist/source/index.d.ts", // for TypeScript and IDE suggestions
  "unpkg": "./dist/browser/umd/index.min.js", // for browsers which directly use unpkg.com CDN
  "jsdelivr": "./dist/browser/umd/index.min.js", // or browsers which directly use jsdelivr.com CDN

Personally I do not like mjs, cjs and jsx extensions because of compatibility problems but probably the following matches may work in most cases too:

• solid: .js, .jsx
• main, require: .js, .cjs
• module, default: .js, .mjs

[amoutonbrady]

That's interesting and much more detailed than my first post.

To answer you question, Parcel 2 actually resolved the source key first (see here: https://v2.parceljs.org/features/module-resolution/#package-entry-fields).

I actually though is was a legit thing, but I'm starting to wonder if its not just a Parcel thing (just like the sideEffect key was a Webpackl thing only at first).

I don't like cjs and mjs either. Nobody sain actually do haha.
The main reason I expose the jsx extension is because, as far as I can tell, this is the only way for most bundlers to know to treat this differently. For instance, in the vite plugin I worked on, this has been the only way for me to hook myself into the resolution system and apply solid specific JSX transformation without doing it for every js/ts files.

I'm not entirely sure the unpkg and jsdelivr key should be involved honestly, those seem very specific. I think they both can resolve to the browser entry. On top of that, I'm not sure UMD modules would work well with solid component.. like they'd need to have a window.Solid available globally or something? Perhaps I'm not familiar enough but that's how I understood it at least

The rest is pretty much on par with my thought tho.

Note that I made a typo btw, I had to republish my package. The key in exports should be . not ./.

[ryansolid]

Hmm.. it might be simpler because some of categories just are sort of invalid because of different server client compilation. Anything for SSR that needs compilation is going to need to use solid. While it is conceivable for a server only library with no need to compilation I'm not sure if the main/module fields should have server expectation. Most bundlers do respect browser so that seems ok, but I suspect this is a very rare case. Are there any bundlers we need to worry about that don't support ESM?

Parcel's source is fine but doesn't differentiate between source for server and source for client. So it implies client because of being for Parcel. It also needs to be hacked around, so I'd basically ignore this one.

The one advantage of unpkg and jsdelivr are pre minified. I think it is an ok option if that is something you want to support.

On cjs and mjs mostly a node resolution thing so depending on how the fields are used might just be necessary. Generally if your module is type module use js and cjs (this is what I do for all new libs) or if isn't mjs and js. I prefer the former because I tend to not publish cjs anymore outside of Solid core since any lib that uses it probably should be using solid.

And I agree with @amoutonbrady that since our compilation is special we will be adopting the .jsx extension. While it isn't Solid specific like .vue or .svelte it's enough to indicate that it's special and since we do the non-normal jsx transform we need that in places. It's also an indicator that it's source. It's different in the React ecosystem where you don't need this sort of consideration.

Finally I have no top level "solid" support in anything because it hasn't been a real thing until now. So I think we will just stick to conditional exports.

So honestly the most blown out config I think of for libraries that export components should be like this:

  "type": "module",
  "main": "./dist/index.js", // esm for legacy bundlers, does not support SSR
  "exports": { // for modern node and future bundlers
    ".": {
      "solid": {
         "node": "./dist/server/index.jsx", // for solid server compiler
         "default": "./dist/browser/index.jsx" // for solid client compiler
      },
      "default": "./dist/index.js" // for import in browser
    }
  },
  "types": "./dist/index.d.ts", // for TypeScript and IDE suggestions
  "unpkg": "./dist/umd/index.min.js", // for browsers which directly use unpkg.com CDN
  "jsdelivr": "./dist/umd/index.min.js", // or browsers which directly use jsdelivr.com CDN

And if you don't ship components:

  "type": "module",
  "main": "./dist/server/index.cjs", // cjs for node
  "module": "./dist/server/index.js", // esm for node
  "browser": "./dist/browser/index.js",
  "exports": { // for modern node and future bundlers
    ".": {
      "node": {
        "require": "./dist/server/index.cjs", // for require in node
        "default": "./dist/server/index.js" // for import in node
      },
      "default": "./dist/browser/index.js" // for import in browser and other possible environments
    }
  },
  "types": "./dist/index.d.ts", // for TypeScript and IDE suggestions
  "unpkg": "./dist/umd/index.min.js", // for browsers which directly use unpkg.com CDN
  "jsdelivr": "./dist/umd/index.min.js", // or browsers which directly use jsdelivr.com CDN

99% of the time there are only 3 outputs(since client/server can be handled by isServer): your "solid" jsx source or cjs for node, your compiled for browser esm, and your umd minified for cdn's. If you ignore the cdn's minification and rely on type module.. you only need the one esm output and the jsx if you ship components.

I know I'm cutting a few corners here by ignoring certain legacy support for SSR but practically speaking with these being new solutions I'm ok with that.

The only thing I'm wondering is do we need something other than node to indicate non-node server environments like Deno or Cloudflare. I am tempted to include server everywhere I include node. To be fair this is only a bundling concern but maybe node === all server isn't right.