Both gatsby and next.js as well as other open source projects have an /examples folder at the root of the repo, showing off various setups and combining them with other tools. Example:
We also have an “examples” folder but there are 2 problems with it, I think:
The examples in the folder do not have any JS/TS files. This is because both the mars-theme-example and the twentytwenty-theme-example link to their respective theme files located in /packages by using lerna.
I think this is very confusing for new users as the vast majority of devs are not familiar with lerna and monorepos. It makes it seem like the examples are incomplete or at best difficult to understand.
Because of that, the examples also look different than what you get if you just run npx frontity create <my-app>. If you run that, your starter theme is “copied” into your machine and you can go ahead and edit it.
I propose that we create self-contained examples in the /examples folder that do not depend on anything in the /packages. Then, we could move the current examples to another folder like /dev-examples (or some better name) so that we can continue to develop our themes against the latest version of the framework as we have so far.
Currently we only have 3 examples whereas next / gatsby have in the order of a 100 examples each . I know that each theme contains many use cases, but I would suggest moving some of the examples from the frontity-demos repo into the examples folder. Those should have proper READMEs and
As a bonus, I believe this doing this would make our examples more accessible and reduce the amount of repetitive questions on the forum about common problems.
The first step for us is having a collection of demos/examples under the same repo. This repo should have has proper explanations on the content and purpose for each demo.
From there we can decide where is the best place to locate it (maybe a link to this repo on the README is enough)
Yes. lerna doesn’t work with local npm packages, at least when I tried.
Maybe we could move all the frontity-demos org to a single repo in the frontity org, something like frontity/examples or frontity/demos.
If we want to keep both, I guess we need to decide what is an “example” and what is a “demo”. I think NextJS and Gatsby examples are more like “how to use X library with Next/Gatsby” than demos of things you can do with them. Am I right?
We could name it just projects, which is consistent with the “Frontity project” name and the name we are going to use in the e2e system.
yes, I think that’s more or less correct . But I would argue that a “how to use library X with frontity” or “how to do X with frontity” is the kind of demos/examples that we most need and they should go into the main repo in the /examples folder.
Then we could move the current /examples into the projects (good name by the way)
We’ve started creating some (well organized) demos in the frontity-demos organization under the same repository → frontity-examples
The idea is to have small examples for specific use cases that can help the community understand every feature.
Every folder has a frontity project and a README…md explaining the purpose of the demo.We have created so far:
Contact Form in Footer → how to put a contact form (or any other content fetched from the WP REST API) in the footer of each page on the site.
Processors → to show the use of processors in Frontity
Head Tags → to show the use of @frontity/head-tags package
This is related to this conversation → Simplify the examples in `/examples` in the main frontity repo
We still need to figure out a good naming and work on different “levels” of demos/examples/showcases.
But this is a good starting point to have good references we can use in our conversations w/ the community (edited)
Is there a way we can add a codesandbox link to them so people can test them out right on their browser?
It looks like in this case, even if we add the sandbox.config.json file it won’t work, like I explained in Update codesandbox template automatically, right? Maybe we have to do something manually?
Great to see this @juanma. The readme files are really clear, and I love the idea of having a repo with a bunch of simple examples.
I think that the frontity-examples repo could be under the main organization so people can find it easily. I feel like right now these examples are a bit hidden.
Maybe they’re worth a mention in the docs as well, I couldn’t find any reference to them after a quick search.
. I know that each theme contains many use cases, but I would suggest moving some of the examples from the