Site: Svelte Cookbook/ Examples

[pngwn]

A few people have asked to see more in-depth examples for things like CSS, and SSR.

I don't know if this would add too much noise to the docs but they might be great topics for a cookbook. Ths has been briefly discussed in the past but I couldn't find an issue for it.

Some examples of things that could be covered:

• CSS: "Something that demonstrates cssvars, the global modifier and component scopes together would be excellent for new comers." (Quote from a fine individual on Discord)
• SSR - "include an example of SSR with hydration on the client. :pray: (without sapper - via express if possible)" (Quote from yet another fine individual on discord).
• Preprocess: We see a lot of questions about preprocessing, less, scss, etc. We could provide an example configuration and explanation to enable users add their own (or even write their own) preprocessors.
• Testing: This is an obvious one. Testing framework agnostic explanations.
• Routing: Again without sapper. We've been asked about Routing without Sapper a number of time recently. A good example implementation with a popular routing library or a 'blessed' Svelte one would be cool.

Anyone have any thought on this?

And if this is a good idea, what else should be covered?

Edit: Another request from discord.

"A couple more cookbook ideas would be RxJS and XState integration and usage. For RxJS simple API usage in Svelte is best, saw this svelte-observable repo that seems to wrap RxJS in Promises, that is a little strange seeing that RxJS is a better alternative to Promises. For XState using stores seems to be the way to go. Best would be to have a store per XState Machine and the Machine can swap in and out alternate Statecharts. Statecharts are just serializable objects that can be stored and fetched from any local or remote DB."

Edit: Another.

Had a few suggestions for a static blog deployed to netlify, with support for markdown (maybe mdx too). This might be better on the Sapper docs, and might require a custom Sapper template but is definitely a great idea.

[alinnert]

More in-depth examples definitely sound like a good idea. I've seen cookbooks quite a few times already and they are always helpful.

I'd also like to see some examples about "async data flow". I'm currently building an app that loads settings from IndexedDB using localForage. And I'm having trouble finding out how to organize my code to make it work. My problems are that top-level-await is not supported and store's update and set functions don't really support async functions either. My next idea is to write an async init or load function and call it from main.js or the root component.

(I already can load the settings, but my components write the default data back to IndexedDB before they get updated with the data that's already stored in the DB...)

So, I think it would be nice to see some more advanced examples about async data flow, especially on page load. Is this within the scope of these cookbooks/examples?

[pngwn]

I think any common usecase could be featured in a cookbook. I think using async data is a common fetaure of many web apps, so having some examples of how to approach it seems reasonable.

At the end of the day it's about making life as simple as possible for svelte users, both old and new, so it is valuable from a learning point of view, I think we can find somewhere for examples such as these. Whether that is in the form of a cookbook, or something else.

[andymans]

As an addn'l suggestion, how about showing how to achieve commonly used UX in svelte? As an example, how to achieve the animated sorting list shown in react-flip-move - this should fit quite well with how to use the FLIP technique. Another interesting one is a grid component like this old (and dodgy) implementation at svelte-animated-list.

[o-t-w]

Documenting working with GraphQL would also be useful. Noticed this question in Stack Overflow https://stackoverflow.com/questions/56065845/how-to-do-graphql-and-graphql-subscriptions-with-svelte?r=SearchResults

[maxmilton]

Another topic worth covering is any dev tooling or code editor enhancements. Main thing I'm thinking of is eslint-plugin-svelte3 and perhaps common editor settings.

[o-t-w]

I would recommend Docusaurus for this project. It takes markdown files and formats them really nicely with syntax highlighting and navigation. I'm happy to set up a repo for people to contribute to if it is helpful.

[btakita]

We can do the cookbook as a sapper app. This will improve the svelte/sapper ecosystem. It would be great to have markdown svelte components, for example. I might do this is nobody beats me to it.

There is not much work involved. svelte.dev & sapper.svelte.com is already built to render markdown. I have created a few sites that read markdown & link to edit the markdown (a la graphql's technique).

I even have a sapper template that is markdown content rendering enabled.

[maxmilton]

Wouldn't it make more sense contextually to put this in the Sapper docs site; https://sapper.svelte.dev?

We could also have a repo for the more complex examples but then it would need to be maintained etc.

[Conduitry]

Another idea for the cookbook: this information about async reactive declarations. I'm not sure whether that sort of information belongs there, but I don't think it belongs in the API docs really.

[btakita]

I like the idea of having a template for patterns, along with other meta-patterns. The async reactive declarations pattern above has a nice markdown format.

Having comments would also be good. Discourse, a github issues based system (gitment), or a svelte alternative would be interesting.

Or better yet, something that is forkable, like gists would be a good place for patterns (in Readme.md) with an example (usable in the repl?). Gists also support comments, btw.

[pngwn]

The cookbook will probably live on the svelte site alongside the examples, docs and tutorial.

The cookbook will probably need to focus mostly on generic patterns that can be adapted to different situations as well as more in depth guides / discussion on topics covered by the tutorials (as well as some that aren't covered there). This doesn't exclude specific integrations but they will need to be used as examples that can be used to achieve similar things with other libraries.

I don't think we want the cookbook to become a collection of tutorials regarding how to use certain libraries and tools with svelte. A set of more generic recipes or deep dives into topics would probably serve people better and have broader application.

I haven't forgotten about this, I'll probably look into how/ where it can fit into the current site over the next week or two.

[pngwn]

I'm not convinced about comments that isn't really the purpose in my mind, I see it more like extended documentation.

As for gists/ repls, many of the topics won't be runnable in the repl so that will need to be considered on an article by article basis I think.

[btakita]

I'm not suggesting the cookbook, on the svelte site, be there to introduce 3rd party libraries. I'm suggesting that the cookbook apps be self-contained & forkable. 3rd parties could host their own cookbook recipes, possibly using a forked cookbook from an already established pattern.

Discussion is not necessary, but could be useful for critiquing a pattern. This would be useful for people who are proposing a pattern to the community or for people who want to gather feedback on an experiment.

This would be like an executable proposal. I understand that it's beyond the original intent of having canonical patterns on the Svelte site, but it would facilitate the community to express their own patterns. Now that we have markdown preprocessors :+1:, the documentation itself can be an app.

I suppose it all comes down to tooling. It should be easy to author a pattern. A set of implicit (possibly explicit) patterns to author patterns may be useful.

[brandonxiang]

SSR is absolutely important!

[swyxio]

linking the vue equivalent https://vuejs.org/v2/cookbook/

[Wolfr]

If I get to an advanced CSS example I'll keep this in mind. Subscribing.

[pngwn]

@Conduitry I posted these cookbook entries over at the community site as some of them fit well in that context, especially anything to do with patterns and integrations. Should we do the same for the Svelte constructs/ features such as reactivity, stores, SSR (maybe), etc? Or should we try to find a place on the Svelte site for them? These are more 'Svelte fundamentals' than "how do I do x" or "how do I use x".

[swyxio]

i do believe "fundamentals" are better placed on the main docs, or even better, make them individual blogposts!

[Conduitry]

Yeah I think there are some things that definitely make sense to fit in somewhere on the official site - there are a few important things about how Svelte works that we ought to be explaining somewhere, but which would cause too big of a detour to just mention them inline on the API page. There are probably some things on the API page that might be better off moved out to this separate articles once they exist. Things like 'which assignments trigger reactivity' or 'how do reactive blocks decide their dependencies and running order' are both subjects that we really need to be covering better than we are - and things like the store contract are currently probably a bit overwhelming to list so early in the API docs, and may be also better off as its own page.

To @sw-yx's comment which just came in as I was typing this, having these be blog posts would avoid the problem of creating another section for these guides to live in, but doing that doesn't feel quite right to me. These really should be an official part of the documentation, and blog posts - even though they hang around for a long time - feel more ephemeral. Blog posts also inherently have a date attached to them, and something that's come up several times is how much to edit blog posts to keep them in line with current information and how much to keep them as snapshots of reality at the time they were posted.

[pngwn]

Makes sense, I'll have a think about this, and try to go through the backlog to see which docs issues would be solved by these 'deeper dives', I know there are several.

This is slightly unrelated but what about bringing back the 'guide' (a la svelte2) and having that alongside the API docs?

We could slim down the API docs to be just API and move the more explanatory prose into the guide. It could help improve both sides. The API docs have slowly morphed to be more guide-like with more in-depth examples.

[Conduitry]

I've been trying to put the 'docs' label on issues that aren't bugs but which we aren't doing a great job explaining why they're not bugs.

I think having the return of a Guide section makes sense. I don't have much of an opinion yet of whether it should be one big page with navigation like the API page or split out into separate pages per topic.

[pngwn]

Yeah, the docs label is very useful. A lot of questions around reactivity.

But yeah, I don't have any clear ideas around that at the moment. It is probably going though out existing docs and taking a look at what might make sense in a guide-like section instead.

If we can go some way to mimicking the structure of the API docs we could just link where there is a relevant guide section to an API section, perhaps.

[pngwn]

Oh, and I could finally give our lovely easing widget a real home.

[benmccann]

We do have https://sveltesociety.dev/recipes already. Do you think that linking there would be sufficient or do you think something on the official site is required?