Snowpack: Snowpack Programatic API

[FredKSchott]

Original Discussion: https://www.pika.dev/npm/snowpack/discuss/115
/cc @jlkiri, @antony, @FredKSchott, a bunch of others

import {install, createConfiguration} from 'snowpack';

Work Todo

• [ ] PR 1: Export our current internal config creation function as createConfiguration(). Must have unit tests.
• [ ] PR 2: Export our current install command logic as an install() function. Must have an integration test.

[antony]

I had a little go this morning, but my lack of typescript skills held me back.

I would like to pass in a javascript object with config, and I believe cosmiconfig will allow this, with a custom loader. We can then leverage config validation as the cli does.

The bit that stumped me was how to build the entypoint list, since this requires that internal class which would need to be exposed. I think the method to load config would need to build those from config.

On my phone so apologies if I'm not making much sense right now, will clarify a bit later on.

[FredKSchott]

Nope, that's all pretty in line with what I'd expect. So it feels like we want something like this:

import {install, createConfiguration} from 'snowpack';

const config = await createConfiguration({ /* user-provided config */});
await install(['react', 'react-dom'], config);

Is that enough for the usecase everyone's picturing? The only thing not exposed is could how Snowpack scans your file tree to generate the list of install targets automatically by reading your file system... but at that point you should just run the CLI from Node via execa :)

[jlkiri]

Something like createConfiguration is definitely needed. In my library I (and other people I guess) have to output a json with configuration first before running install via execa.

[FredKSchott]

Cleaned up the issue to be more actionable. Would still love help on this one if anyone is interested.

You can also see a current workaround here: https://github.com/pikapkg/create-snowpack-app/issues/9#issuecomment-639643197

[jlkiri]

I'll try the first one (not yet sure how long it's going to take, need to read the code)

[jlkiri]

I tried to implement it in #449, but I'm not sure how to test it, so I hope someone helps me.

[jlkiri]

I might as well try doing the same with install function.

[FredKSchott]

That would be great! I think just exposing it would be a great start, and then making sure that you add https://www.npmjs.com/package/@pika/plugin-build-types so that consumers can get the right type declarations when they use the programatic API.

The only problem with how it's written right now is that it assumes that it's being called as a CLI always, so it doesn't hesitate to call console.log, or maybe even process.exit() in a couple of cases where errors are hit. I think that can be tackled in a separate follow-on PR.

[jlkiri]

One easy thing we can do is to accept functions like onError instead of logError so that the consumer can decide what to do with errors.

[FredKSchott]

+1 for renaming logError and logUpdate to onError and onMessage.

We should also start to move those messages from strings to machine-readable objects, with a unique message.code property + a toString() function. For example:

onMessage((msg) => console.log) // Warning: 1+ circular dependencies found via ...
onMessage((msg) => JSON.stringify) // {"code": "CIRCULAR_DEPENDENCY", ... }
onMessage((msg) => {
  if (msg.code === "CIRCULAR_DEPENDENCY") {
    // special handling
  }

[FredKSchott]

Update: a first-class, programmatic API for the installer is being worked on in #1042