Skip to content

Commit 73edcdd

Browse files
pedrolamaspedrolamas
authored
docs: update development instructions (#1825)
Signed-off-by: Pedro Lamas <pedrolamas@gmail.com>
1 parent 68e6a21 commit 73edcdd

2 files changed

Lines changed: 184 additions & 14 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 66 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,75 @@
11
# Contributing to Fluidd
22

3-
Fluidd exists as an independent client of Moonraker, and by extension - Klipper.
4-
Fluidd is built on VueJS, using TypeScript.
3+
Fluidd is an independent web client for [Klipper](https://github.com/Klipper3d/klipper)
4+
(via [Moonraker](https://github.com/Arksine/moonraker)), built with Vue 2.7 and TypeScript.
55

6-
- Source should always pass the linting rules defined, with no warnings or type errors.
7-
- A clean develop is preferred. This means squashing, and rebasing your feature branches prior to merge.
8-
- PR's should off a branch other than develop or master.
9-
- Commit messages should follow the [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) standard, and should have a Signed-off-by line, for example;
6+
Contributions of all kinds are welcome — bug reports, feature requests, code, and
7+
translations. This document covers the process and rules. For setup instructions and a
8+
tour of the codebase, see the
9+
[Development guide](https://docs.fluidd.xyz/development/).
1010

11-
```sh
12-
feat: My feature.
11+
## Before you start
1312

14-
Some description.
13+
- Read the [Development guide](https://docs.fluidd.xyz/development/) — it covers the
14+
Dev Container, running Fluidd locally, and a quick architecture overview.
15+
- After cloning, run `npm ci && npm run bootstrap` to install dependencies and set up
16+
the Git hooks that pre-validate your commits.
1517

16-
Signed-off-by: Your Name <your email address>
18+
## Branching and pull requests
19+
20+
- Create your work on a feature branch from `develop` — for example,
21+
`feat/my-feature` branched from `develop`. Do not open pull requests from
22+
`develop` or `master` directly.
23+
- **Pull request titles must follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/)**.
24+
This is enforced by CI.
25+
- Accepted pull requests are squashed and rebased onto `develop` when merged.
26+
27+
## Commits
28+
29+
- Use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) for every
30+
commit message. Allowed types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`,
31+
`test`, `build`, `ci`, `chore`, `revert`, `types`, `i18n`.
32+
- The commit subject must be **50 characters or fewer** — enforced by the
33+
`commit-msg` Git hook.
34+
- Every commit must include a `Signed-off-by` line. The easiest way is to commit with
35+
`git commit -s`. Signing off acknowledges the
36+
[Developer Certificate of Origin](./developer-certificate-of-origin) and must
37+
contain your real name and a current email address. Example:
38+
39+
```text
40+
feat: my feature
41+
42+
Some description of what changed and why.
43+
44+
Signed-off-by: Your Name <your@email>
1745
```
1846

19-
- By signing off on commits, you acknowledge that you agree to the [developer certificate of origin](/developer-certificate-of-origin).
20-
This must contain your real name and a current email address.
47+
## Code quality
48+
49+
Source must pass linting and type-checking with **zero warnings and zero type errors**.
50+
Before pushing, run:
51+
52+
```bash
53+
npm run lint
54+
npm run type-check
55+
npm run test
56+
```
57+
58+
CI runs the same checks (plus `npm run circular-check` and a production build) on
59+
every pull request.
60+
61+
## Translations
62+
63+
Translations are managed via [Weblate](https://hosted.weblate.org/engage/fluidd/) — do
64+
not edit non-English files in `src/locales/` directly. New strings should be added to
65+
`src/locales/en.yaml`; Weblate handles the rest. See the
66+
[Localization section](https://docs.fluidd.xyz/development/#localization) of the
67+
Development guide for more.
68+
69+
## A note on `CLAUDE.md`
2170

22-
After cloning the repo and running `npm install`, we recommend running `npm run bootstrap` to install a couple of git hooks that will pre-validate all new commits.
71+
The `CLAUDE.md` file in the repository root is an exhaustive reference written for AI
72+
coding assistants (Claude Code, Cursor, and similar tools). It documents architecture,
73+
patterns, and gotchas in detail. Humans are welcome to read it as a deeper second
74+
source, but the canonical onboarding doc for human contributors is the
75+
[Development guide](https://docs.fluidd.xyz/development/).

‎docs/docs/development.md‎

Lines changed: 118 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,123 @@ Contributions are welcome! Please review the
1414
[CONTRIBUTING.md](https://github.com/fluidd-core/fluidd/blob/develop/CONTRIBUTING.md)
1515
file before submitting a pull request.
1616

17+
## Architecture overview
18+
19+
This section is aimed at developers comfortable with Vue and TypeScript who want a
20+
quick map of the codebase. For an exhaustive reference, see the `CLAUDE.md` file at
21+
the repository root — it was written for AI coding assistants but works as a deep
22+
second source for humans too.
23+
24+
### Stack
25+
26+
- **Vue 2.7** with [Vuetify 2](https://v2.vuetifyjs.com/) for UI components
27+
- **TypeScript** throughout, with class-style components via
28+
[`vue-property-decorator`](https://github.com/kaorun343/vue-property-decorator)
29+
- **Vuex** for state management — namespaced modules mirror Klipper and Moonraker
30+
domains
31+
- **[Vite](https://vitejs.dev/) 8** as the build tool and dev server
32+
- **[Vitest](https://vitest.dev/) 4** with `jsdom` for unit tests
33+
- **Node.js 24** — pinned in `.node-version` (engines: `^22.12.0 || ^24`)
34+
35+
### How it talks to Klipper
36+
37+
Fluidd does not talk to Klipper directly. Instead, the browser keeps a single
38+
WebSocket connection open to Moonraker, which in turn talks to Klipper:
39+
40+
```text
41+
Browser ⇄ WebSocket (JSON-RPC) ⇄ Moonraker ⇄ Klipper
42+
```
43+
44+
All printer commands and live state updates flow through that single socket. The
45+
client lives in `src/api/socketActions.ts` — for printer control and state, call
46+
its methods rather than making direct HTTP requests.
47+
48+
A few features still use HTTP: file upload and download (via `axios` for progress
49+
reporting — `fetch` cannot report upload progress; see `src/mixins/files.ts`),
50+
camera WebRTC signalling, and the initial `config.json` fetch at startup.
51+
52+
### Repository layout
53+
54+
```text
55+
src/
56+
├── api/ WebSocket JSON-RPC client (socketActions.ts)
57+
├── components/
58+
│ ├── common/ Shared dialogs and status components (auto-imported)
59+
│ ├── layout/ App shell: AppBar, AppDrawer, etc. (auto-imported)
60+
│ ├── ui/ Reusable widgets: AppBtn, AppDialog, etc. (auto-imported)
61+
│ ├── settings/ Settings page components
62+
│ └── widgets/ Feature widgets — one folder per feature
63+
├── views/ Page components, lazy-loaded by the router
64+
├── store/ Vuex modules — one per Klipper/Moonraker domain
65+
├── mixins/ Shared component logic (StateMixin, FilesMixin, ...)
66+
├── plugins/ Vue plugins (i18n, socketClient, vuetify, filters)
67+
├── router/ Vue Router (hash mode)
68+
├── locales/ i18n YAML files (managed via Weblate)
69+
├── scss/ Global styles and Vuetify variable overrides
70+
├── util/ Helper functions
71+
├── workers/ Web Workers (G-code parser, MJPEG stream, Monaco language servers)
72+
├── typings/ Global TypeScript declarations (Klipper, Moonraker namespaces)
73+
└── types/ UI-specific TypeScript types
74+
```
75+
76+
### Patterns you'll meet immediately
77+
78+
**Class-style components.** Every component uses decorators — no Options API or
79+
Composition API. Components that need printer state extend a mixin via `Mixins()`:
80+
81+
```typescript
82+
@Component({ components: { /* ... */ } })
83+
export default class PrinterWidget extends Mixins(StateMixin) {
84+
@Prop({ type: String, required: true })
85+
readonly label!: string
86+
87+
get klippyReady (): boolean {
88+
return this.$typedGetters['printer/getKlippyReady']
89+
}
90+
}
91+
```
92+
93+
**Vuex modules** live in `src/store/<name>/` with a standard layout
94+
(`index.ts`, `state.ts`, `getters.ts`, `mutations.ts`, `actions.ts`, `types.ts`).
95+
Use `$typedState` and `$typedGetters` for type-safe access from components.
96+
97+
**WebSocket calls** go through `SocketActions` methods. Pass a `wait` parameter
98+
(constants in `src/globals.ts`) to drive UI loading state — for example,
99+
`wait: Waits.onPrintPause`.
100+
101+
**Auto-imported components.** Anything under `src/components/common`, `layout`, or
102+
`ui` is registered automatically by `unplugin-vue-components` — no manual import
103+
needed. The generated `components.d.ts` at the repo root is regenerated on every
104+
build; do not edit it by hand.
105+
106+
**Cross-component messaging.** Use the Vuex store for shared state, or the
107+
`EventBus` (`src/eventBus.ts`) for ephemeral events such as flash messages.
108+
109+
**Logging.** Use `consola`, not `console.log` (configured in `src/setupConsola.ts`).
110+
111+
### Where to add things
112+
113+
- **A new widget** → create a folder in `src/components/widgets/<name>/` and import
114+
the component where it's used.
115+
- **A new route** → add a lazy import to `src/router/index.ts` and create the page
116+
in `src/views/<Name>.vue`.
117+
- **New store data** → add a module under `src/store/<name>/` with the six
118+
standard files (including the module's `index.ts`), register it in
119+
`src/store/index.ts`, and update `src/store/types.ts` so `RootModules`,
120+
`RootState`, and `RootGetters` pick it up.
121+
- **A new translation key** → edit `src/locales/en.yaml`. Weblate handles the
122+
other languages — do not edit them directly.
123+
- **A new icon** → add an MDI mapping to the `Icons` object in `src/globals.ts`,
124+
then use it as `<v-icon>{{ $globals.Icons.myIcon }}</v-icon>`.
125+
126+
### Going deeper
127+
128+
The repository's `CLAUDE.md` file is an exhaustive reference originally written
129+
for AI coding assistants. It covers topics that are out of scope for this quick
130+
orientation — the auth state machine and token-refresh policy, the full list of
131+
build-toolchain gotchas, every Vuex module, and more. If you've outgrown this
132+
overview, that's the next stop.
133+
17134
## Dev Container in Visual Studio Code
18135

19136
Fluidd includes a Dev Container configuration to easily open with Visual Studio Code
@@ -82,7 +199,7 @@ npm run test
82199

83200
Follow the instructions from [Python](https://www.python.org/) to install Python 3.
84201

85-
### Install dependencies
202+
### Install Python dependencies
86203

87204
```bash
88205
cd .../path/to/fluidd/docs

0 commit comments

Comments
 (0)