4

I'm developing a Svelte module for publishing as an npm package. I'd like to include examples that are longer than a few lines. What's the standard approach for this?

I don't think it makes sense to burden the original module with additional dependencies needed for examples. I could create a separate Github project mymodule-examples, but it also feels wrong to separate the module and examples into two repositories. Due to the nature of sveltekit, each example requires several files.

Anna
  • 2,645
  • 5
  • 25
  • 34
  • I haven't used it myself yet, but: https://kit.svelte.dev/docs/packaging – voscausa Apr 04 '23 at 18:29
  • Thanks for chiming in @voscausa. I've read that part of the docs but can't find any suggestions on where to put example apps using my module. – Anna Apr 04 '23 at 18:44
  • I don't think an NPM package is the correct place to add examples. You should just include a README that points to an examples repository. Why should you force consumers to download samples every time? Developers should just read the documentation, learn from the examples, and that should be it. – José Ramírez Apr 12 '23 at 07:21

3 Answers3

2

update: Quote from docs that makes me feel this is the suggested way to organize/publish libraries made with SvelteKit:

A component library has the exact same structure as a SvelteKit app, except that src/lib is the public-facing bit, and your root package.json is used to publish the package. src/routes might be a documentation or demo site that accompanies the library, or it might just be a sandbox you use during development.

I believe it is possible to control what is uploaded to NPM:

[The files field] tells npm which files it will pack up and upload to npm. It should contain your output folder (dist by default)...

To exclude unnecessary files (such as unit tests, or modules that are only imported from src/routes etc) you can add them to an .npmignore file. This will result in smaller packages that are faster to install.

So, you can manually control what is uploaded to NPM via:

  • package.json files field (whitelist)
  • .npmignore (blacklist)

As for dependencies, I believe you can control these with dependencies and devDependencies:

  • dependencies: modules needed by your library.
  • devDependencies: modules needed by examples, but not by your library.

Further reading:

Leftium
  • 16,497
  • 6
  • 64
  • 99
  • Thanks for taking your time. My main question is what the standard approach is for supplying examples for my (svelte) npm package? – Anna Apr 14 '23 at 13:01
  • Ah, are you suggesting that I include the examples in the github repository, but upload the package without examples (and example dependencies) to npm? – Anna Apr 14 '23 at 13:02
  • @Anna: Correct. (Include the examples in the github repository, but upload the package without examples (and example dependencies) to npm) – Leftium Apr 14 '23 at 13:03
  • @Anna: I updated my answer with a quote from the Kit docs. – Leftium Apr 14 '23 at 13:14
2

Appears to me the following ways:

/examples directory:

Create an /examples folder in your module's repo with separate subdirectories for each example. Add a README.md for instructions and include /examples in .npmignore to avoid publishing it to npm.

Monorepo:

Use a /packages folder in your repo containing your main module and separate example projects. Each example will have its own package.json for managing dependencies.

Submodules:

Create separate repositories for each example and include them as submodules in your main module's repo inside an /examples folder. Provide instructions for cloning and initializing submodules in your README.md.

SolessChong
  • 3,370
  • 8
  • 40
  • 67
1

I would stick with using an readme.md file that has the markdown formatted instructions for your package & markdown code blocks for small examples of how to use your package. If you need anything more complex than just simple examples for your packages API I would create a simple github pages documentation site to refer users of your package too.

Cam
  • 43
  • 10
  • Thank you. Would you put the github pages in the main repository? – Anna Apr 19 '23 at 08:38
  • Yeah, you would create a repository just for your docs portion of the web app / api. I suggest looking at Laravel & torchlight for highlighting of your codeblock. This is how laravel handles it for the docs on their official site https://github.com/laravel/docs & https://github.com/laravel/laravel.com – Cam Apr 21 '23 at 05:47