Top-level examples directory

[cartogram]

As we move into the release of the hydrogen CLI package for project creation, I've been thinking on the side about the dev package. I'd like to introduce some minor changes that will help distinguish packages from example code as well as support more examples within the repo. These examples would be for folks to inspect or start from using the cli, npx, on StackBlitz. etc... (Note: It might make sense that absorb our examples repo, but we don't have to make that decision now.)

I suggest we create a new folder at the root of the repo, /examples, that will be where these examples live. This is similar to other frameworks, and will increasingly be standard as tools like turborepo push for this approach. It also just makes sense to split these up (though I don't know all the history/context of why we started with the dev package that isn't really a package to begin with).

Does anyone hate or see potential issues with:

• Creating a new folder at examples/default-starter
• Moving all of the contents of dev to that folder
• Using this to seed the CLI init command, npx, yarn create, etc...
• Adding more examples here as time goes on...

cc @jplhomer

[jplhomer]

I like this.

though I don't know all the history/context of why we started with the dev package that isn't really a package to begin with

This was because I wanted to leverage monorepos. I hadn't considered moving it to a better location and using e.g. package.json#workspaces.

Note that this will require us to update our hydrogen.new redirect which tells StackBlitz where to pull the GH contents.

cc @vixdug @morganmccunn need to be intentional about where we place examples and whether we continue to use https://github.com/Shopify/hydrogen-examples

[cartogram]

Note that this will require us to update our hydrogen.new redirect which tells StackBlitz where to pull the GH contents.

Where does this logic live? I am only aware of the github action and stackblitz branch.

[jplhomer]

(Matt and I spoke offline about this)

[jplhomer]

Update: I spoke to @tarynmusgrave today, and the DevRel team is seeking a basic "examples" folder to start populating "how-to" examples.

These aren't full Hydrogen sites, and thus don't belong in Shopify/hydrogen-examples.

What I propose is that they also leverage this /examples folder in the monorepo.

• This means they can direct people to StackBlitz and use the GH URL params to clone a specific folder
• They can also direct users to npx degit shopify/hydrogen/examples/dark-mode if they want to spin up a specific example
• These examples will not use the full starter template so we don't need to avoid getting out of sync.
• These examples will not be options in the create CLI unless we specific "promote" them as such.

Any concerns about the above approach?

cc @scottdixon @morganmccunn

[cartogram]

No major concerns, just a few questions to help clarify:

• Who would be the owner of these examples and responsible for maintaining them as new versions of hydrogen, etc... are released?
• Would we be accepting 3rd-party examples as contributions?
• It would help to know more specifically what the examples/how-to's you are thinking?

[benjaminsehl]

With Next the /examples folder is maintained by third parties — this is awesome because there are so many to look through and you can see how basically any tool is integrated. When I was starting out with React, it was such a helpful resource to see how others were approaching the same things I was looking to do.

That said, there have been a large handful of times I've run into dated examples, especially as they switched away from things like getInitialProps. Personally, I never blamed Next/Vercel for that, and it was just something to be aware of, and I'd always compare/contrast to the "official" examples and the patterns they used.

I do agree that with the CLI, you probably shouldn't be able to get a /examples project — you're not in a place where you can get a larger context, and are expecting things to "just work". It would be better to have CLI starters be "officially" supported (whether built within Shopify or simply approved/monitored)

Thanks for starting this RFC @cartogram!

Related: Would be great to have #425 as something we can track/upvote somehow, in an easier way than string comments. I'd be happy to start building out some examples if there was community demand.

[cartogram]

Would be great to have #425 as something we can track/upvote somehow, in an easier way than string comments. I'd be happy to start building out some examples if there was community demand.

I like this! Would be cool to get something up quickly that does this.