Skip to content

Latest commit

 

History

History
72 lines (62 loc) · 3.14 KB

DEVELOPMENT.md

File metadata and controls

72 lines (62 loc) · 3.14 KB

SilverBullet Development Guide

Good practices

  • After each significant change, run the typechecker, linter, and tests.
  • Write unit tests for new functionality first
  • Always keep DEVELOPMENT.md up to date with new best practices, based on guidance.

Commands

  • Build: deno task build
  • Test: deno task test
  • Test single file: deno task test /path/to/test.ts
  • Run all Lua tests: deno task test common/space_lua/lua.test.ts
  • Lint: deno task lint
  • Format: deno task fmt
  • Type checking: deno task check
  • Watch server: deno task watch-server <PATH-TO-SPACE>
  • Watch web: deno task watch-web
  • Watch plugs: deno task watch-plugs

Code Style

  • TypeScript: Use explicit types for function parameters and return values
  • Imports: Group related imports together, sort alphabetically within groups
  • Naming: camelCase for variables/functions, PascalCase for classes/interfaces/types
  • Error handling: Use explicit error types and handle errors gracefully
  • Tests: Write unit tests for new functionality using @std/assert for assertions (e.g., assert, assertEquals)
  • Comments: Focus on "why" not "what", especially for complex logic
  • Prefer const over let when variable won't be reassigned
  • In Lua: use camelCase for variables and functions
  • Tests end with .test.ts

Architecture Overview

Plugin System (Plugs)

  • PlugOS: Extension framework with System, Plug, Sandbox, and Syscalls components
  • Hooks: Extension points (commands, events, slash commands, widgets)
  • Manifest: Configuration for plugins defining functions, permissions, and dependencies

Data Models

  • Pages: Markdown documents with frontmatter, structured as ObjectValue
  • Documents: Any file type (images, PDFs) with metadata
  • Objects: Structured data extracted from pages, supporting tagging and attributes

Key Design Patterns

  • Event-driven architecture with EventHook system
  • Middleware layers with composable SpacePrimitives implementations
  • Syscall pattern for sandboxed plugin functions
  • Command pattern for UI and programmatic actions
  • Hook system for extension points
  • Client-server synchronization with offline support
  • Template rendering with query language for data extraction

Directory Structure

Top-level Directories

  • /Library: Standard library shipped with SilverBullet
  • /cmd: Command-line interfaces and entry points
  • /common: Shared core functionality for both server and client
  • /lib: Utility libraries and internal modules
  • /plug-api: API exposed to plugins (syscalls and utility functions)
  • /plugs: Built-in plugins that provide core functionality
  • /server: Server-side implementation (HTTP, storage)
  • /web: Client-side/browser implementation
  • /website: Documentation site content

Key Areas

  • /common/space_lua: Lua scripting implementation with parsers and runtime
  • /lib/plugos: Plugin system core functionality
  • /plugs: Plugs for core functionality (editor, indexing, etc) distributed with the system
  • /web: Client implementation
  • /web/cm_plugins: CodeMirror editor extensions
  • /web/hooks: Client-side hook implementations
  • /web/syscalls: Client-side specific syscall implementations