-
Notifications
You must be signed in to change notification settings - Fork 10.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
chore(gatsby): output apis.json for current valid API list #16061
Conversation
I have no idea why unit tests failed -- seems unrelated 😢 |
Adding I think this happens because we do already have ---edit |
@pieh good catch -- it's fixed now. Agreed, it's kinda why I've been leaning towards quite a bit less snapshots. They're kind of a fragile "easy" way to test things, when it seems better to perform tests on specific properties of the object's shape. |
Note: after changing documentation to 10.x, |
|
||
const output = apis.reduce((merged, [output, api]) => { | ||
merged[api] = output.reduce((mergedOutput, doc) => { | ||
if (doc.namespace.startsWith('.')) { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I can't really figure out what this does - worth adding small note why this is here?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah -- this should block, good catch!
It's because of this line in gatsby-ssr.js, it's captured as an item in the output when it's not really an API.
/**
* Object containing options defined in `gatsby-config.js`
* @typedef {object} pluginOptions
*/
That creates:
{
"namespace": "pluginOptions"
}
whereas every other one is an export so namespace is .replaceRenderer
for instance.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Right, I now do remember I similar thing to our docs (just implemented differently):
gatsby/www/src/pages/docs/browser-apis.js
Lines 15 to 20 in aea3e39
const funcs = sortBy( | |
this.props.data.file.childrenDocumentationJs.filter( | |
doc => doc.kind !== `typedef` | |
), | |
func => func.name | |
) |
(and I didn't add note on what it does and why it's there :S)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this is good to go. Left small question, but don't consider it blocker.
Description
This PR begins implementing one chunk of the work required to improve the experience outlined in #16055.
Specifically, this PR outputs an
apis.json
file that we can then distribute with NPM (and query with e.g. unpkg).This uses a doclet
@gatsbyVersion
to denote when an API is available. This will be used to deliver richer error messages (or warnings) like so:A harder problem to solve is if we tweak an existing API (e.g. to pass a new utility or something) but I'd contend that we can either: 1) not solve that problem, or 2) Solve it later with additional metadata. As an example of this problem,
createTypes
was a new utility passed tosourceNodes
in gatsby@2.2.0.The idea is we'll progressively improve the error message when/if we add more metadata to
apis.json
in the future. For context, the below is a sampleapis.json
that will be produced with this PR.Any thoughts @gatsbyjs/core? Any metadata that is currently missing that we could use to improve this experience?
Related Issues
Begins implementing #16055.