Svelte 5: API docs solution

[techniq]

Since the AST has changed in Svelte 5 (and is not a public API guarantee), currently sveld's ComponentParser does not work, which we use to generate the API docs for each component (LayerChart as well).

Svelte 4	Svelte 5

although the instance AST looks identical for a very basic example:

Svelte 4	Svelte 5

[techniq]

Actually the issue might be that Svelte 5 now natively supports Typescript, but in Svelte 4 it would be preprocessed away (I believe).

[ryanatkn]

If you'd like to borrow ideas/code I got a usable amount working here: https://github.com/ryanatkn/svelte_docinfo_sketch

[techniq]

@ryanatkn This looks great! Let me dig in and give it a test with Svelte UX (and LayerChart if all goes well).

Does this only support Svelte 5 syntax ($props, etc)? One of the challenges is I'm hoping to keep Svelte UX and LayerChart 1.x to be Svelte 3-5 compatible (and thus can not use Svelte 5 syntax yet), and make 2.x a breaking changes and require Svelte 5. I would love to find a solution that allows this iterative transition, but that might be too challenging.

With Svelte 5 going public VERY soon (looking at you Svelte Summit), I'll be going all in on migrating to Svelte 5 very soon, but would love to do it as iteratively as possible.

[ryanatkn]

I hope it helps, I'm happy to answer any questions. Yeah it's only Svelte 5, my hacky recommendation would be to detect runes and use Sveld for v3/4. I wouldn't want to discourage anyone from trying to to extend either Sveld with my sketch's stuff or the other way around, but the intregration doesn't look easy - starting from Sveld and using this as a guide may be easier. I haven't seen confirmation of their plans.

The main limitation of mine is that it currently only looks at the AST. I may either use ts-morph or the Svelte language server like Sveld to infer types - exports for example don't have them. (but if I use ts-morph I'm guessing I'd be duplicating a lot of work of the language server, and that's what Sveld does already - I'll look into this) Props are easier and the basics seem to work, but it it would probably be more correct with inference.

[techniq]

In the short term I decided to remove the API docs as it was the only show stopper from deploying the doc sites with Svelte 5, and there currently isn't a solution (yet) that supports Svelte 3-5 syntax.

After a few other priorities are shipped, I plan to start on the Svelte 5 migration of both libraries, but it will be a breaking change (no Svelte 3/4 support). I wanted to validate the current codebase could run on Svelte 3-5 to ease the transition for projects to Svelte 5 (incremental, not big bang) which running the full docs of both Svelte UX and LayerChart accomplishes.

@ryanatkn Thanks so much for your project. I'll likely be leveraging it once both projects are on Svelte 5.

[techniq]

This looks very promising... https://github.com/svelte-docgen/svelte-docgen

Gave their playground a quick test with Svelte 4 and 5 syntax and worked great. Only a single release so far, but looks very robust. I've seen another project using it via pkg.pr.new packages, which looks like the way to go for now.