Context and Problem
I want to minimize maintenance and dependency management
- Remove features of repo that are overkill
Libraries I don’t want to maintain for now:
- ADR libraries (used to generate architectural decision logs)
- Storybook (it is very heavy on dependencies, forces me to include React in my project)
But I still want to document my project efficiently
Considered Options
Considered:
- mdsvex
- ✅ simple and flexible
- ✅ based on Svelte
- ❓feature complete
- ❓can be easily used for styleguide
- ❌ old Svelte version
- bookit
- ✅ based on Svelte
- ❓feature complete
- ❓can be easily used for more than styleguide
- ❌ light on doc
- Histoire
- ✅ feature rich and flexible
- ✅ replaces Storybook
- ❓can be easily used for more than styleguide
- ❓dependencies
- ❌ based on Vue (but has project for Svelte)
Decision
➖ Removed
To simplify maintenance, I will stop using the ADR system, as it is also a bit overkill.
Removed dependencies in root package.json:
"dependencies": {
"adr-log": "2.2.0",
"madr": "2.1.2"
}
Removed scripts in root package.json:
"scripts": {
"build:doc": "adr-log -d ./packages/doc/decisions",
"build:design": "node ./packages/design/node_modules/.bin/build.js",
"build": "npm run build:doc",
},
Removed storybook
This was a lot dependency removals. I considered and made this decision while upgrading SvelteKit. I departed from a fresh SvelteKit lib project for the ui package, and it did not include storybook. I then felt I did not to want to add it back (see reasons at the start of this document).
➕ Kept or added
ADR templates are useful, I’m keeping them for reference and for decision docs.
These are the resources used for ADR:
- Markdown Any Decision Records
- arc42 template
- HTML Sanity Checker Architecture
- biking2, Architecture and API
- Architecture decision record
🚧 Chosen option for doc: mdsvex
- Used mdsvex svelte adder which went smoothly using this command for pnpm:
pnpm dlx svelte-add@latest mdsvex
- It wasn’t very clear how to load markdown files dynamically - this post helped : Build a static site with SvelteKit