[1.0] Plugin packaging file structure

Quoted from: https://github.com/gatsbyjs/gatsby/issues/324#issuecomment-297261038

On why no dist/lib folders — it’s mainly because I don’t want to have to rely on compiling the modules and not using a dist/lib folder means you have the option of writing straight uncompiled JS. I want to add support for sites to have a “plugins” folder where more complex sites can split up functionality into multiple plugins. We could add some sort of config in plugin’s package.json to say where code is but the code for finding plugins is simpler by saying code is at the root of the plugin. I guess there’s nothing preventing us from reading something out of a plugin’s package.json which says where the code is at. We can’t use the common convention of the index.js exporting the location of things because gatsby-node/gatsby-browser/gatsby-ssr code are all incompatible with each other given possible webpack/babel enhancements to the language.

Currently there are a lot of plugins which are defined in packages but don’t follow normal package rules, where you have package.main pointing to the entry point, and exporting everything from there. I am trying to understand why the normal package.main wouldn’t be sufficient.

If you want to create a plugin without compiling the source, wouldn’t it be enough to point package.main to the source file and omit the build step?

Regarding incompatibility between gatsby-node/gatsby-browser/gatsby-ssr, can’t we give them their own babelrc config if they differ in how they should be compiled?

If in the future you want to support a plugins folder from client code directly, I think it wouldn’t be hard to make a distinction from regular packages and just read a bunch of js files and treat them as plugins. I don’t see your point about “finding the sources” if you use the standard package.main for it.

To me it feels dangerous to ignore normal npm package semantics, since I don’t see a good reason. Right now I see a lot of index.js which are empty with a “noop” comment. Why are they not exporting the functions and components?

I guess I might be missing the big picture, but I feel that every package could have

• all its sources in /src
• optionally compile to /dist
• point package.main to the entry point
• entry to export all functions and components.

Also the bin folders in the gatsby and gatsby-dev-cli packages should IMO just go into the src directory. Then their source can be simplified and cleaned up with babel. In the case of gatsby it can be compiled with a different babel preset to support node < 4

I was trying to improve debugging (in VSCode debugger) by generating source maps. But those source maps ended up in the packages’ root. This triggered my OCD and I started cleaning the structure and cli code 😅 I won’t make a PR now because I wasn’t expecting this discussion, but I can finish it maybe later when it is clear to me what the structure will be.

[Alxandr]

I would suggest going with actual functions rather than a single registerAPI('namehere', .... Much easier to deal with registerWebpackConfigHandler(() => ...) (or whatever naming convention you want to use. easier to deal with typing, auto discovery by supporting IDEs etc…

[KyleAMathews]

Ooooo… yeah! I really like this idea. Yeah I’ve thought about doing some sort of scan on startup of what people are exporting to find errors but this is much easier. We probably want to do some sort of registering callbacks with strings to make validation easier. Maybe something like:

const api = require('gatsby').pluginApi

api.registerAPIHandler(`modifyWebpackConfig`, ({ config, stage }) => {
// ...
})