You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-[WSL](https://learn.microsoft.com/en-us/windows/wsl/install) (for Windows users)
61
+
-[Git Bash](https://git-scm.com/install/windows) (for Windows users)
50
62
51
63
2.**Clone the Repository**
52
64
@@ -56,6 +68,182 @@ cd Helio
56
68
```
57
69
58
70
3.**Run the initialization script**
71
+
> :warning: Use Git Bash if running on Windows.
72
+
59
73
```bash
60
74
yarn run init
61
75
```
76
+
77
+
## FAQ
78
+
79
+
### Repo layout
80
+
81
+
#### What is the difference between `apps/` and `packages/`?
82
+
83
+
-**`apps/`** - deployable websites. Each one is its own Nuxt app with its own `nuxt.config.ts`, routes, and deploy target (`docs`, `netlogo`, `learn`, `nettango`).
84
+
-**`packages/`** - shared, non-deployable code consumed by the apps via the `@repo/*` workspace alias. Things like `vue-ui`, `nuxt-core`, `tailwind-config`, `markdown`, `utils`, and the shared `eslint-config` / `typescript-config`.
85
+
86
+
If something ships to users as a URL, it belongs in `apps/`. If multiple apps need it, it belongs in `packages/`.
87
+
88
+
**Packages follow the single-responsibility principle.** Each package should do one thing, Unix-style, and do it well - `markdown` renders markdown, `tailwind-config` holds themes, `utils` provides pure helpers, `vue-ui` owns components. A well-scoped package should rarely need to change, because its surface area is narrow. If you find yourself reaching into a package to add unrelated behavior, that is a signal the behavior belongs in a new package (or in the app consuming it), not bolted onto an existing one.
89
+
90
+
#### What does `@repo/*` resolve to?
91
+
92
+
Nothing magic - it's just the Yarn v1 workspace alias for `packages/*`. You can `cd` into any package and edit it directly; apps pick up the change through the workspace symlink.
93
+
94
+
#### What is `external/` for?
95
+
96
+
It holds the NetLogo extension documentation sources (not a workspace package). The `docs` app pulls from it when generating extension reference pages. Treat it as an input to the markdown pipeline, not as code you import.
97
+
98
+
#### Where do static assets, favicons, and fonts live?
99
+
100
+
Three places, by scope:
101
+
-**`static/`** (repo root) - shared favicons and cross-site assets.
102
+
-**`apps/<app>/public/`** - assets owned by a single app.
103
+
-**`@repo/vue-ui/assets/`** - brand logos, images, and fonts shared across apps, imported from components.
104
+
105
+
#### How do I add a new app or a new package?
106
+
107
+
Copy the closest existing sibling (e.g. `apps/nettango` for a new app, or any small package for a new one), rename it in `package.json`, and add it to the workspace. The [creating-nuxt-project](./docs/guides/creating-nuxt-project.md) guide covers the Nuxt side but is somewhat outdated - use it as a reference, not a script. Note: `packages/template` is **not** a scaffolding template; it's a Mustache/Handlebars template engine.
108
+
109
+
### Styling
110
+
111
+
#### How do I style an app? Why are there two themes (`docs-theme` and `netlogo-theme`)?
112
+
113
+
All styling is centralized in `@repo/tailwind-config` under `scss/`. Each app picks a theme by importing it from its own `app/assets/styles/main.scss`:
@includemeta.load-css("@repo/tailwind-config/scss/netlogo-theme.scss"); // or docs-theme.scss
119
+
}
120
+
```
121
+
122
+
-**`netlogo-theme`** - the marketing/website look used by `netlogo` and `nettango`. It applies the NetLogo brand defaults globally and scopes documentation-like typography (headings, TOC, prose) to a `.docs` class so only opt-in regions get the docs treatment.
123
+
-**`docs-theme`** - used by the `docs` app (docs.netlogo.org). It applies docs typography globally (headings, TOC, prose) plus docs-specific layout rules for things like dictionary entries and scroll-margin.
124
+
125
+
Both themes are composed from the same building blocks (`netlogo-mixins.scss`, `docs-mixins.scss`), so edit the mixins when you want a change to affect every site, and edit the `*-theme.scss` file when you only want to change one family.
126
+
127
+
Unless fixing a bug or making a global change, treat these as open-for-expansaion, closed for modification. You may introduce a new theme if desired following the same pattern.
128
+
129
+
### Components & UI
130
+
131
+
#### Why are there three UI libraries (`@repo/vue-ui`, Nuxt UI, and Reka UI)? Which should I use?
132
+
133
+
They are layered, not alternatives:
134
+
135
+
-**Reka UI** - the lowest level. Unstyled, accessible Vue primitives (menus, dialogs, popovers). Use directly only when you need a primitive no one has wrapped yet.
136
+
-**Nuxt UI v4** - sits on top of Reka UI and provides styled, themeable components. Available in any app that pulls in `nuxt-core`.
137
+
-**`@repo/vue-ui`** - our in-house component library. This is what you should reach for first. It contains NetLogo-branded components (navbar, footer, catalog, widgets), shared composables, brand assets, and HOCs. Components are auto-imported when the package is wired into `nuxt.config.ts` (see `packages/vue-ui/README.md`).
138
+
139
+
Rule of thumb: **vue-ui → Nuxt UI → Reka UI**, in that order. Only drop down a level when the one above does not have what you need.
140
+
141
+
#### Where do I put a new shared component?
142
+
143
+
In `packages/vue-ui/src/components/` (or `widgets/` for larger, composed pieces). It will be auto-imported by any app that has vue-ui wired into its `nuxt.config.ts`. Remember to import component prop types from the component's own path, e.g. `import type { Props } from '@repo/vue-ui/src/components/Button.vue'` - vue-ui does not pre-bundle its types, it relies on the consuming Nuxt app's context.
144
+
145
+
### Nuxt & shared config
146
+
147
+
#### Why is there a `nuxt-core` package if every app already has its own `nuxt.config.ts`?
148
+
149
+
`@repo/nuxt-core` is the shared baseline for every Nuxt app in the repo. It provides the common Nuxt layers, modules, plugins, runtime config schema (`runtime.config.schema.ts`), the default layout, the shared `main.scss` entry, and composables like `useWebsite`. Apps extend it and override only what is app-specific - this is why you will see very thin `nuxt.config.ts` files in `apps/*`.
150
+
151
+
#### What does `useWebsite` from `@repo/nuxt-core` do?
152
+
153
+
It's a small shared composable that exposes the current site's identity (name, full name, description, URL, keywords, logo) as a reactive ref, pulled from `runtimeConfig.public.website`. Use it whenever a component needs to render something site-aware (page titles, meta tags, footer copy, OG images) instead of hard-coding strings per app:
154
+
155
+
```ts
156
+
const website =useWebsite()
157
+
useHead({ title: website.value.fullName })
158
+
```
159
+
160
+
On the client it's wrapped in `createSharedComposable`, so every caller gets the same ref - there is no cost to calling it from many components.
161
+
162
+
### Content authoring
163
+
164
+
#### How do I author or build content with the markdown system?
165
+
166
+
Content authoring (frontmatter, directives, custom components, how Nuxt Content is wired into the apps, and how documentation is generated from markdown) is covered in its own guide. Start here:
167
+
168
+
-[Building Markdowns](./docs/guides/building-markdowns.md) - the authoritative guide for the markdown pipeline powered by `@repo/markdown` and `@repo/netlogo-docs`.
169
+
170
+
### Dev workflow & tooling
171
+
172
+
#### How does Turborepo fit in? Do I need to learn it?
173
+
174
+
Mostly no. All day-to-day commands go through the root `package.json`:
175
+
176
+
```bash
177
+
yarn dev # turbo run dev - starts every app in parallel
178
+
yarn build # turbo run build - builds everything with caching (apps are excluded)
179
+
yarn lint # turbo run lint
180
+
yarn check-types # turbo run check-types
181
+
yarn test# turbo run test
182
+
```
183
+
184
+
Turbo handles task ordering (`^build` means "build my dependencies first"), caches outputs in `dist/`, `.next/`, etc., and reads `.env` files as part of the cache key. If a build acts stale, `turbo.json` is where inputs/outputs are declared.
185
+
186
+
To work on a single app only, `cd` into it and run its own `yarn dev` - Turbo is not required at the leaf level.
187
+
188
+
#### How do environment variables work?
189
+
190
+
Env files are a global Turbo dependency (`.env`, `.env.local`, and any `.env*` in an app). The `yarn init` script generates a starting `.env` via the per-package `create:env` task. `.env` is gitignored - never commit it. If you add a new variable, declare it in the relevant runtime config schema so it is typed and validated.
191
+
192
+
#### Why doesn't my change to a package show up in the app?
193
+
194
+
Most of the time it just works - `@repo/vue-ui` in particular is sourced as a directory (via `components: [{ path: vueUiSrc, watch: true }]`), so edits HMR into the app live. If you changed something outside that watched path (a composable, a type, a package's `package.json`, or anything consumed through a built export), restart `yarn dev`.
195
+
196
+
#### How do I debug a failing Turbo build?
197
+
198
+
Run `yarn build --force` to bypass the cache, or `turbo run build --filter=<app>` to isolate one target. Remember that `.env*` changes invalidate the cache, and per-task inputs/outputs are declared in `turbo.json`.
199
+
200
+
#### What are the repo health scripts I see in `package.json`?
201
+
202
+
-`yarn check-dupes` - flags duplicated dependencies across workspaces.
|`yarn dev`| Starts every app in parallel via Turbo (only packages). |
216
+
|`yarn build`| Builds all workspaces with caching (only packages). |
217
+
|`yarn lint`| Runs ESLint across all workspaces. |
218
+
|`yarn check-types`| Runs TypeScript type-checking across all workspaces. |
219
+
|`yarn test`| Runs the test suites. |
220
+
|`yarn format`| Formats `*.{ts,tsx,md}` with Prettier. |
221
+
|`yarn pre-push`| Runs the same checks the pre-push hook runs — use it before pushing. |
222
+
|`yarn clean-up`| Clears stale file watchers (macOS fix when `dev` misbehaves). |
223
+
224
+
### App-level (run from `apps/<app>/`)
225
+
226
+
Every Nuxt app exposes the same baseline scripts:
227
+
228
+
| Command | What it does |
229
+
| --- | --- |
230
+
|`yarn nuxt:dev`| Starts just this app's dev server. |
231
+
|`yarn nuxt:prepare`| Regenerates Nuxt's `.nuxt/` types and module artifacts. Run this after pulling, switching branches, or when your editor complains about missing types. |
232
+
|`yarn nuxt:build`| Builds this app for production. |
233
+
|`yarn nuxt:preview`| Serves the built output locally. |
234
+
|`yarn lint` / `yarn lint:fix`| Lints just this app. |
235
+
|`yarn check-types`| Type-checks just this app. |
236
+
237
+
Individual apps may expose extra scripts (e.g. `docs:*` in `apps/docs`). Check the app's `package.json`.
238
+
239
+
## Conventions
240
+
241
+
-**Apps are deployable, packages are shared.** If it has a URL, it lives in `apps/`. If multiple apps consume it, it lives in `packages/`.
242
+
-**Packages are single-responsibility.** One package, one job. Add a new package rather than widening an existing one.
243
+
-**Workspace imports use `@repo/*`.** Never reach into a sibling by relative path.
244
+
-**UI layering: vue-ui → Nuxt UI → Reka UI.** Reach for the highest layer that satisfies your need.
245
+
-**Shared components live in `@repo/vue-ui`.** Component prop types are imported from the component's own path (`@repo/vue-ui/src/components/Foo.vue`).
246
+
-**Styling is centralized in `@repo/tailwind-config`.** Edit mixins for cross-site changes; edit a `*-theme.scss` for single-family changes. Themes are open for extension, closed for modification.
247
+
-**Shared Nuxt config goes through `@repo/nuxt-core`.** App-level `nuxt.config.ts` files should stay thin and only override what is app-specific.
248
+
-**Never commit `.env` files.** They are gitignored and generated by `yarn init`.
249
+
-**Windows contributors use Git Bash**, not WSL, for the setup scripts.
Copy file name to clipboardExpand all lines: docs/guides/managing-dependencies.md
+3Lines changed: 3 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,4 +1,7 @@
1
1
## Dependency Management
2
+
3
+
> :warning: This guide is no longer relevant and needs to be updated. (TODO)
4
+
2
5
Managing dependencies might be the most tricky part of Helio development. Helio uses a monorepo structure managed with [yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/), [yarn](https://yarnpkg.com/) and [turborepo](https://turbo.build/repo).
0 commit comments