Contributing Guide
Relevant source files
The following files were used as context for generating this wiki page:
This guide outlines the standards, workflows, and technical requirements for contributing to the Svelte Effect Runtime (SER) project. The repository is structured as a pnpm workspace containing several publishable packages, including the core runtime, compiler plugins, and editor tooling integrations.
The primary goal of contributors is to maintain the integrity of the effectful execution environment while ensuring compatibility with Svelte 5. Contributors must adhere to strict coding styles, specialized git etiquette, and a rigorous testing protocol to ensure that changes to syntax or runtime semantics do not break the developer experience or production builds.
Sources: CONTRIBUTING.md:1-6, README.md:31-40, SKILL.md:1-10
Workspace Architecture
The project is organized into modular packages within the modules/ directory. Each package serves a specific role in the SER ecosystem, ranging from the core transformation logic to VS Code extensions.
| Package | Purpose |
|---|---|
modules/svelte-effect-runtime | The core module containing the runtime, compiler plugin, and remote/server helpers. |
modules/svelte-effect-runtime-grammars | TextMate and tree-sitter assets for syntax highlighting and editor awareness. |
modules/svelte-effect-runtime-language-server | Integration layer for editor-side diagnostics and LSP features. |
modules/svelte-effect-runtime-vsix | The VS Code extension package for launching the language server. |
.tests | Centralized Vitest suites for all workspace packages. |
Sources: CONTRIBUTING.md:12-25, README.md:31-40
Development Workflow
The repository requires Node ^22.12.0 or >=24.0.0 and uses pnpm managed via Corepack. The build system relies on Vite+.
Common Commands
Contributors should use the following commands at the root level to ensure workspace consistency:
# Install dependencies
corepack pnpm install
# Run full test suite
corepack pnpm run test
# Run full workspace build
corepack pnpm run build
# Type check and lint
corepack pnpm run check
corepack pnpm run lint
Sources: CONTRIBUTING.md:8-10, CONTRIBUTING.md:32-55, package.json:6-23
Build and Test Flow
The following diagram illustrates the relationship between code changes and the validation pipeline.
The workspace build must be run whenever package exports, grammars, or language server code are modified to ensure generated output remains synchronized.
Sources: CONTRIBUTING.md:12-25, CONTRIBUTING.md:37-41, package.json:6-23
Coding Standards
Contributors must follow specific naming and formatting conventions to ensure the codebase remains maintainable and readable.
Naming and File Structure
- snake_case: Used for functions, variables, and methods.
- PascalCase: Used for classes, types, interfaces, and Svelte components.
- kebab-case.ts: Used for filenames.
- Directories: Group related files by directory rather than using filename prefixes (e.g.,
internal/transform.ts).
Sources: CONTRIBUTING.md:58-61, AGENTS.md:3-7
Implementation Style
Contributors are encouraged to favor modern, declarative syntax over imperative loops. This includes extensive use of optional chaining (?.), nullish coalescing (??), and array methods like .some(), .find(), and .map().
Function logic should be "airy," utilizing blank lines to separate logical phases and guard clauses. Variables must be grouped at the top of the function.
/** Example of logic separation and phase comments */
export function example_function() {
const variable = "value";
/** Phase 1 - Early guard */
if (!variable) return;
/** Phase 2 - Execution */
return variable;
}
Sources: AGENTS.md:21-43, AGENTS.md:92-113
Documentation and JSDoc
Every exported entity must include a JSDoc block. The block must contain a brief description, an @example, a @since version tag, and detailed descriptions for all @param and @returns tags. Bare comments (//) are strictly forbidden; all comments must use the /** */ format.
Sources: CONTRIBUTING.md:63-64, AGENTS.md:134-142, AGENTS.md:167-184
Testing and Validation
Tests are categorized by their target impact and located within the .tests/ directory.
- Runtime/Compiler:
.tests/svelte-effect-runtime/runtime - Grammars:
.tests/svelte-effect-runtime-grammars/runtime - Language Server:
.tests/svelte-effect-runtime-language-server/runtime
When a transform changes generated code, contributors must assert both on the generated shape and the user-facing behavior. Small fixtures are preferred over large application-scale tests to isolate boundaries (e.g., SvelteKit or Effect control flow).
Sources: CONTRIBUTING.md:72-83
Git Etiquette and Release Process
The project follows a strict branch-and-merge policy.
Commits
- Use short, conventional messages (e.g.,
fix: preserve remote failures). - Do not push to
masterwithout human approval. - One branch per coherent change. If work expands, branch from the current branch.
Sources: CONTRIBUTING.md:85-88, AGENTS.md:11-18
Versioning and Releases
All publishable packages must share the exact same semantic version. Versions are tracked in the package.json files of the four core modules.
If the version numbers between modules drift, the release workflow is configured to fail.
Sources: CONTRIBUTING.md:90-100, AGENTS.md:196-224
Summary
Contributing to Svelte Effect Runtime requires a deep respect for the established coding patterns and the delicate balance between the Svelte compiler and the Effect runtime. By following the standards for naming, Airy logic, and synchronized versioning, contributors ensure that the project remains a reliable tool for effectful Svelte development.