How to integrate?

[Wolfr]

Let's say I have this super simple dir structure with a few svelte components.

How would I integrate Svench in a good way? Do I place a svench dir inside my project and reference files outside using folder backtracking? (../../src/Badge.svelte)

[Wolfr]

The repo: https://github.com/Wolfr/jui

[rixo]

It really depends on what you're doing... This is not something I intend Svench to be opinionated about.

As a developer who uses it as a development tool (i.e. my components mostly go from 0 to almost 100% being developed in the workbench before they are dropped into the actual application), I just put the .svench file beside the component they're documenting.

./src/components/Foo.svelte
./src/components/Foo.svench

So referencing the target component is never a hassle for me, it's just one dot away. Also, I'm very happy with having the menu hierarchy in Svench mirror the layout of my source directory.

Now I understand that you might want to have a dedicated Svench folder to be able to control your pages (i.e. menu) layout, or just because you don't like collocating different concerns in the same place. In this case, yes, you'll need to be able to reference the target components in a way your system / bundler will understand (we're not going to overload Node's resolution algorithm).

In this case, I'd personally avoid importing paths like ../../src/Badge.svelte though, because they're impractical and way too sensible against refactors. I would have an alias to my src folder so that I'd import this as @/Badge.svelte from anywhere (generally implemented with a symlink svench/node_modules/@ -> .. because all IDE tooling automatically support that -- sometime need to double with aliases from the bundler down the road, because some deployment envs don't support symlinks).

[rixo]

I realize I answered this as a support question, but the truly interesting question here is: how do you want to integrate?

The main use case I'm considering is something like this:

• you drop a Rollup plugin in your existing config, and this will parse your FS for Svench files

• Svench files would be collocated with the thing they document, and hence the menu hierarchy would follow the layout of your source files

• the workbench is a dev tool, and so you run it as a separate process as your main app, both during development and production (the workbench would typically not be deployed in production, but that's not a hard rule: it could be published to some doc site)

How the last point will be tackled is still very much an open question. We'll need a dedicated index.html, a web server, etc... How to make this the most frictionless for the user?

That being said, I know that you have quite different perspectives, so I'd love to hear about your own ideal scenario and, also, it would help me greatly if you can help me draw the specs on this question (generally).

What would be the best way for you to integrate Svench into your project?