Better documentation

[Garito]

Describe the problem

I can't follow the documentation

Describe the proposed solution

Write the documentation without assumptions

The demo code has no field name so I don't know were to put it (I assume by the demo code that should go to main.js but no explanation about how or why)

By the demo too, I assume that vite.config.js should be modified but will this need different vite.config.js for allowing to use the component as a normal component vs webcomponent. Am I right?

Would be perfect if the documentation provides a step by step instructions

thanks!

Alternatives considered

none

Importance

i cannot use svelte-retag without it

[patricknelson]

Hi @Garito, thanks for your consideration! Sorry if this is a long response, but I hope it helps.

... normal component vs webcomponent...

Just to clear this up from the top, here's the terminology I use (since it can get confusing):

• Svelte component: This is your Example.svelte component which, inside other Svelte components .svelte files would normally be referenced as <Example />. This is what you might refer to as a "normal component".
• Web component: This is a.k.a. the "custom element" or custom HTML tag that svelte-retag will setup for you, e.g. <example-tag> (note that all custom element tags require a hyphen).

If it helps: svelte-retag can actually be used anywhere you are building code for the browser, not just in Vite (while it does support some awesome Vite-specific features like HMR for custom elements / web components). However, you could easily incorporate it into a variety of other build systems (like rollup or anything that supports modules) since it's really just plain JavaScript that runs in the browser.

So, it actually makes relatively few assumptions. However, it is safe to assume that most people (maybe like in your experience) will be coming into this using Vite, so I think we could probably flesh out the examples a bit better!

The demo code has no field name so I don't know were to put it (I assume by the demo code that should go to main.js but no explanation about how or why)

Since you are using Vite: Basically yes, in a default Vite project, your call to svelteRetag() would just go into your main.js file. As long as that file is referenced on the page you plan on using your custom elements. i.e. Just be sure to include that main.js file anywhere you'll have your <example-tag> web component version of your Example.svelte Svelte component.

By the demo too, I assume that vite.config.js should be modified but will this need different vite.config.js for allowing to use the component as a normal component vs webcomponent. Am I right?

Actually, no! With a default Svelte project, no additional changes at all should be required to both vite.config.js nor your svelte.config.js files. Basically all you would need to do is simply do what was already described in the README.md. Make sure you:

1. If you're starting from scratch (sounds like not, since you already mentioned you had a main.js), but if not already started, one easy way to get started is to just
   • Run npm create vite@latest, follow prompts and
   • Select Svelte as framework
   • Select Javascript as variant
2. Install svelte-retag, run npm install svelte-retag
3. Copy/paste the code from README.md and just edit the parts that apply to you, e.g.
   • Edit and replace instances of HelloWorld and 'hello-world.svelte' to correspond with the name/location of your component
   • Use whatever tag name you want, e.g. hello-world

Give that a shot and let me know if that works for you and if not what you're stumbling into. I'll keep this issue open so that I can use your experience and perspective when adjusting the documentation. For now, I'll just update the current README.md to include a note that no additional changes are required to vite.config.js nor svelte.config.js and point out that the example starter code would go into your main.js file (if using Vite).

Hope this helps.

[Garito]

Hi @patricknelson
Thanks for your time
I have a sveltekit lib with a component
I create a new sveltekit project
install the component and yours
add src/main.js with this code:

import svelteRetag from 'svelte-retag';

import Form from 'lt-form-2';

svelteRetag({
	component: Form,
	tagname: 'lt-form',
	attributes: ['openapi', 'schema', 'ui', 'values', 'form', 'components', 'extras' ],
});

create a test.html at the root of the project:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Document</title>
  <script type="module" src="src/main.js"></script>
</head>
<body>
  <lt-form openapi="http://localhost:9000/openapi.json" schema="Faucet"></lt-form>
</body>
</html>

start a python simple http server to test it
it raises this error at the browser's console:

Uncaught TypeError: Failed to resolve module specifier "svelte-retag". Relative references must start with either "/", "./", or "../".

and i get stuck

[patricknelson]

Sorry I gotta ask, just in case, but: Did you make sure to first run npm install svelte-retag?

If so, then you might also need to ensure that you have your local dev server (JavaScript-based) running as well - this is what is running Vite (via SvelteKit) which will build your src/main.js file so that it then see NPM managed packages (like svelte-retag).

[patricknelson]

For SvelteKit, starting that server should be pretty simple too. See here: https://kit.svelte.dev/docs/creating-a-project

e.g.

npm create svelte@latest my-app
cd my-app
npm install

# this is the important step in your case, should start local vite dev server
npm run dev

[Garito]

From package.json
"svelte-retag": "^1.3.1",

I'm using a python server to serve the test.html
What can I do to use the library under this condition? npm run build or similar?
Shouldn't be the goal to produce a .js file that you can import anywhere to use the custom element?

[patricknelson]

Yep. Technically this is all outside of the scope of svelte-retag, however, I have encountered a similar learning curve myself when dealing with Vite since it is a server (as well as a build tool). For example, while you're using Python as your back-end, I use PHP. 😅 Much of the time (at least in the typical Vite and Svelte world) people will be running Vite in local development as their primary local dev server (alone) and then build a static site or do the hosting through SvelteKit itself (without Python, Ruby, PHP, etc).

How Vite works: The way it works is that it transforms code on demand. The issue you're seeing right now is that you're just loading the plain src/main.js file raw (untransformed and uncompiled). However, Vite will take that src/main.js file and compile it on-demand when you request it (see "source code" a little bit below this link). When you're done with development, you would use Vite to perform a build (lots of configuration options there) at which point then you could serve just with your Python server (or whatever server you want).

For development however, in our case, we need to perform what's called a "back-end integration" in Vite world, see: https://vitejs.dev/guide/backend-integration.html

So, in your case:

1. In development, you will probably need 2 servers:
   • Your existing python server (looks like that is running on localhost:9000
   • A Vite development server (e.g. npm run dev) which is running on localhost:5173
2. In production, you'll need to find a way to run your build and ensure your Python app points to your final build JS file.

This is a bit more in Vite land than Svelte-retag itself but I hope this helps. I know this is something I might want to document as well since a prime use case is for folks like us who are not running a 100% JavaScript stack. 🤔

p.s. I'd recommend using just plain Svelte instead of SvelteKit. I'm not 100% sure if it matters either way but I think it'll be simpler and less confusing if you go that way and avoid the extra stuff you don't need (layouts, routes and etc). In this case svelte-retag is purely focused on allowing you to define custom elements.

[patricknelson]

This is where it gets extremely variable since every person's back-end setup is going to vary (e.g. PHP vs. Python and etc). But what I do in PHP is similar to this:

<?php if (isViteRunning()) { ?>
	<!-- development -->
	<script type="module" src="http://localhost:5173/@vite/client"></script>
	<script type="module" src="http://localhost:5173/main.js"></script>
<?php } else { ?>
	<!-- production -->
	<script type="module" src="/dist/main.js"></script>
<?php } ?>

And all that is served over localhost:80 in my case (this would be your Python server). And Vite is then running on localhost:5173 when you run something like npm run dev (depending on what's in your package.json). Hope this helps!

p.s. Still working on some doc tweaks.

[patricknelson]

p.s. @Garito if it helps, the attributes below isn't necessary unless you want them to be "reactive" (i.e. ensure that changes to the attribute after page load are also forwarded to your component):

attributes: ['openapi', 'schema', 'ui', 'values', 'form', 'components', 'extras' ],

[patricknelson]

Alright @Garito I setup a PR w/ updated docs #24. You can preview them at the following link, the most relevant section being the step-by-step instructions at https://github.com/patricknelson/svelte-retag/tree/issue-23-example-docs#how-do-i-use-it

I also added some notes about backend integration which you might find useful for reference. Let me know what you think or if you have other suggestions and I can try to integrate that there.

[Garito]

hi again @patricknelson !
After some test, I must conclude that we are missing the build part of the issue
Remember that I was confused with no configuration needed thing?
That's the problem

if you move the main.js to src/lib and add this to your package.json/exports:

"./main.js": {
	"types": "./dist/main.d.ts",
	"svelte": "./dist/main.js"
}

the main.js compiles? to dist but it goes without the proper format and then it doesn't find the packages (retag and my form)

I suggest you look for the proper export config to properly build you lib (perhaps as a svelte package?)
I can't help, yet, with this since I have the same problem with my lib

If I find it first I will open a new issue with the solution
Meanwhile I will watch this repo to see if you find it first

At this point I really appreciate you help and effort so I thank you

[patricknelson]

You're welcome!

I suggest you look for the proper export config to properly build you lib (perhaps as a svelte package?)
I can't help, yet, with this since I have the same problem with my lib

I think you've gone down quite a rabbit hole! I can't help you with the specifics here since I think much of what you're dealing with here is more Vite and TypeScript specific and not related to svelte-retag itself. I wish I could help further, but sadly I'm just very limited on time. If it helps, svelte-retag is extremely simple (at a high level): It is literally just a function that you can call which will simply wrap your Svelte component as web component and perform the customElements.define(...) on your behalf. That's basically it! That said, I'm going to close this out as completed. It looks like everything else you're dealing with is way beyond scope of this project.

However, based on what we discussed here, I've decided to put some additional time into building out a quick demo of the simplest possible MVP (a "Hello World") that you and others can get up and running locally so you can see svelte-retag in action in your local development environment. 🚀 Check it out here! https://github.com/patricknelson/svelte-retag/tree/main/demo/hello-world

Try it out, run it locally and tinker with it. Hopefully you can find a way to make it work in your particular project. Let me know if you do happen to find any bugs or issues with svelte-retag itself! Again, please note that I cannot provide support for Vite configuration or TypeScript itself, since that is outside of the scope of this project.

Thanks!