search

graphql / graphiql

GraphiQL & the GraphQL LSP Reference Ecosystem for building browser & IDE tools.
MIT License
16.08k stars 1.72k forks source link

examples & `build-demo` #2945

Open acao opened 1 year ago

acao commented 1 year ago

Recently in #2922 we tried enabling eslint for examples again, and it caused many issues. Perhaps we can specify a few more important examples as we do in the workspaces config, which are examples intended for things such as monaco-graphql development.

We used to build a few examples on build-demo script in netlify to validate webpack, parcel, etc other bundlers (incl. type checking in the case of webpack) were working with the npm module, and then a script that ran after to copy the build output to a path in the netlify publishing directory. Eventually we just created a separate netlify deploy for the monaco example but I think we disabled that, and that was using a

The graphiql example is also internal to the workspace - should that just use an example as well?

Or should we move examples into each workspace?

So for example

becomes

some I'd like to add

etc

also would be cool to have links to codesandbox/stackblitzes of these examples in the docs

What is the purpose of build-docs and build-demo then? What are the goals of this side of the tooling?

It's possible that we could switch build-docs, which uses typedoc to generate markdown, to run as a pre-commit task, and to check for a diff in CI to ensure the typedocgen commit has been run. or it can be an after-effect workflow on merge.

dimaMachina commented 1 year ago

@acao note ESLint already enabled for examples, what was an issue in that PR that I added all examples to workspaces (instead of several ones) and it caused an issue of netlify deploy due hoisting of dependencies (because we use yarn).

Migration to pnpm will solve these issues, but as you said it totally fine to omit to specify examples for workspaces to boost up speed installing of dependencies.

jonathanawesome commented 1 year ago

This is a great topic for next week's working group meeting!

SJ-Kumar commented 1 year ago

Pls let me know if I can contribute to this task.

acao commented 1 year ago

@SJ-Kumar hey we are moving along but thank you! I'm not sure if we are ready to nest the examples yet, as we are about to undergo some major tooling changes, but perhaps after?

@jonathanawesome I think this was a great example of where the linting rules clash with what you'd expect examples to do. create-next-app uses npm, doesn't import React, and installs everything to dependencies, and avoids the devDependencies entirely which is a not uncommon pattern to see these days, as it doesn't really do much unless you're using npm install --production somewhere.

The next template clashes with our conventions elsewhere, but that shouldn't matter for an example. An example should take whatever the most common stock template and approach is for that bundler/framework (CRA, CNA, etc) and show the minimal implementation from that for certain ends. If we diverge too much from the stock templates for only conventional reasons, people may misinterpret some of those changes as being required (I learned this from experience over the years from questions users asked about our examples).

Now I would still like to move towards the nested examples approach as per graphql-playground and other projects, but I am happy to start checking some of these examples off the list !

SJ-Kumar commented 1 year ago

Thanks for your response. I am happy to contribute whenever required.