Skip to content
Logixlysia
Esc
↑↓navigate↵open⌘Jpreview
On this page

Contributing

Contribute to Logixlysia development

Thank you for your interest in contributing to Logixlysia! This guide will help you get started.

Getting Started

  1. Fork the repository
  2. Clone your fork: 
    git clone https://github.com/<your-user>/logixlysia.git
cd logixlysia
  3. Install dependencies: 
    bun install

Development

Logixlysia is built with:

  • Bun as the runtime
  • TypeScript for type safety
  • ElysiaJS as the web framework

Project Structure

Logixlysia is a monorepo managed with Bun workspaces and Turbo:

apps/
├── docs/          # Documentation site (Blume)
└── elysia/        # Playground demo (Bun + TypeScript + Swagger)
packages/
├── logixlysia/    # The main Logixlysia package
├── bench/         # Benchmarks
├── video/         # Promo video (Remotion)
└── typescript-config/

Inside packages/logixlysia/src/:

src/
├── config/        # Configuration resolution and presets
├── adapters/      # Shared HTTP batch queue and OTLP core
├── context/       # Request context handling
├── extensions/    # Additional features and extensions
├── helpers/       # Utility functions
├── logger/        # Core logging functionality
├── middleware/    # Elysia middleware/plugin hooks
├── output/        # Output handlers and formatters (console, file, rotation)
├── sampling/      # Head and tail sampling
├── types/         # TypeScript types
├── utils/         # Shared utilities
├── websocket/     # WebSocket support
├── ai.ts          # AI-related helpers
├── errors.ts      # Structured error handling
├── index.ts       # Main entry point
├── interfaces.ts  # TypeScript interfaces
├── otel.ts        # OpenTelemetry integration
└── axiom.ts …     # One entry file per adapter (axiom, better-stack, clickhouse, datadog, hyperdx, loki, otlp, posthog, sentry)

Code blocks are typechecked

Every ```ts block in apps/docs/content is compiled against packages/logixlysia/src, so CI fails when an example drifts from the package. Mark a sketch that is not meant to compile with ```ts check=skip and a block that shows a compile error on purpose with ```ts check=expect-errors. A block of bare config keys, like logFilePath: './logs/app.log', is checked inside a config object, and ```ts check=config forces that wrapper when the block’s first line is not a key. Run bun run typecheck in apps/docs to check locally.

Running Tests

bun test

Watch mode:

bun test --watch

Code Style

  • Follow TypeScript best practices
  • Use meaningful variable and function names
  • Add JSDoc comments for public APIs
  • Keep functions small and focused

Changesets

We use Changesets to manage versions and changelogs. If your change affects the published logixlysia package, create a changeset before opening your pull request:

  1. Run bun changeset in the repository root
  2. Select the packages you’ve changed
  3. Choose the appropriate version bump (patch, minor, or major)
  4. Write a clear description of your changes — it will appear in the changelog
  5. Commit the generated file in .changeset/ along with your changes

Docs-only or internal changes (no effect on the published package) don’t need a changeset.

Preview Releases

Every push to main and every pull request publishes an installable preview build of logixlysia to pkg.pr.new. This lets you install a fix straight from a commit or PR before it ships to npm, without consuming a version number on the registry.

Use a preview build when you want to:

  • Reproduce or verify a bug against the latest main.
  • Confirm that a proposed fix in an open PR resolves an issue in your own app.
  • Share a reliable snapshot with maintainers when reporting a bug.

Install a preview by commit SHA:

bun add https://pkg.pr.new/logixlysia@<sha>

Install a preview by pull request number:

bun add https://pkg.pr.new/logixlysia@<pr-number>

The publish step runs from the Preview Release workflow. Once it finishes on a PR, pkg.pr.new posts a comment on that PR with the exact install command.

Preview builds bypass the npm registry and are meant for testing only. Do not depend on them in production — pin a released version from npm instead.

Pull Request Process

  1. Create a new branch for your feature/fix
  2. Make your changes
  3. Run tests and ensure they pass
  4. Update documentation if needed
  5. Submit a pull request with a clear description

PR Checklist

  • Tests added/updated
  • Documentation updated
  • Code follows style guidelines
  • Changes are backward compatible

Questions?

Feel free to open an issue if you have any questions or need help getting started.

Was this page helpful?