@livestore/livestore 0.4.0-dev.21 → 0.4.0-dev.23

package/docs/sustainable-open-source/contributing/docs/index.md

@@ -1,94 +0,0 @@
-# Docs
-
-Please follow LiveStore's [guiding principles](/sustainable-open-source/contributing/info#guiding-principles) when writing docs.
-
-## Writing style
-
-This project broadly tries to follow the [Prisma docs style guide](https://www.prisma.io/docs/about/style-guide/writing-style).
-
-## Use regular sentence casing for titles of navigation item, pages and sections
-
-All titles for navigation items, pages and sections are using regular sentence casing. This means that only the first word and proper nouns (e.g. "Cloudflare Workers" or "Cloudflare Durable Objects") are capitalized.
-
-### Example 1
-
-Good:
-
-```md
-## This is the title of this section
-```
-
-Bad:
-
-```md
-## This is the Title of this Section
-```
-
-### Example 2
-
-Good:
-
-```md
-## This pages is about Cloudflare Workers
-```
-
-Bad:
-
-```md
-##  This pages is about cloudflare workers
-```
-
-## Create proper frontmatter for every page
-
-Frontmatter is YAML metadata at the start of MD/MDX files (between `---` markers) that controls page rendering, navigation, and SEO.
-
-### Required fields
-
-- **`title`**: Page title used for the browser tab, search results, and page heading. Always required.
-- **`description`**: Brief summary (150-160 characters) used for search snippets and social previews. Highly recommended for SEO.
-
-### Optional fields
-
-- **`sidebar`**: Controls sidebar navigation
-  - `label`: Custom sidebar label (defaults to `title`)
-  - `order`: Numeric sort order (lower numbers appear first)
-
-### SEO impact
-
-The `title` and `description` fields directly impact SEO:
-- `title` becomes the `<title>` tag and search result headline
-- `description` becomes the `<meta name="description">` tag and search snippet
-- Both are used for Open Graph and Twitter Card previews
-- OG images are auto-generated at `/og/{slug}.png` using these fields
-
-### Examples
-
-Minimal (title only):
-```yaml
----
-title: Getting started with LiveStore + React
----
-```
-
-With description and sidebar:
-```yaml
----
-title: Getting started with LiveStore + React
-description: How to use LiveStore with React on the web.
-sidebar:
-  label: React web
-  order: 1
----
-```
-
-## Snippets
-
-For snippet guidelines, see: `/contributor-docs/docs/snippets.md`
-
-## Deploying the docs
-
-- Run `direnv exec . mono docs deploy` to build and deploy the documentation to the dev domain (`https://dev.docs.livestore.dev`).
-- Passing `--prod` targets the production domain (`https://docs.livestore.dev`) when you are on `main` (otherwise the command deploys using a branch alias).
-- Use `--site=<slug>` if you need to override the default Netlify site name.
-- Add `--purge-cdn` when you need to invalidate Netlify's CDN cache after deploying; this ensures new edge handlers or content-negotiation changes take effect immediately.
-- CI automatically builds and deploys the docs: `main` updates `https://docs.livestore.dev`, `dev` updates `https://dev.docs.livestore.dev`, and feature branches publish to the dev domain behind a branch alias.

package/docs/sustainable-open-source/contributing/info/index.md

@@ -1,63 +0,0 @@
-# Info
-
-## Before contributing
-
-First of all, thank you for your interest in contributing to LiveStore! Building LiveStore has been an incredible amount of work, so everyone interested in contributing is very much appreciated. 🧡
-
-Please note that LiveStore is still in active development with many things yet subject to change (e.g. APIs, examples, docs, etc).
-
-Before you start contributing, please check with the maintainers if the changes you'd like to make are likely to be accepted. Please get in touch via the `#contrib` channel on [Discord](https://discord.gg/RbMcjUAPd7).
-
-## Areas for contribution
-
-There are many ways to contribute to LiveStore.
-
-### Help wanted for ...
-
-- You can look at ["help wanted" issues](https://github.com/livestorejs/livestore/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) on GitHub for ideas.
-- [SQLite WASM build](https://github.com/livestorejs/wa-sqlite) maintainer (e.g. keeping it up to date with upstream SQLite and wa-sqlite versions)
-- Examples maintainer (e.g. keeping dependencies & best practices up to date)
-- Solid integration maintainer (e.g. keeping it up to date with upstream Solid versions)
-
-### In scope and encouraged
-
-- Documentation improvements
-- Improving examples
-- Test cases
-- Bug fixes
-- Benchmarking
-
-### Potentially in scope
-
-- New features
-- Larger architectural changes in the core library
-- Adding new examples
-- Adding new integrations (e.g. for technologies such as Svelte, Vue, ...)
-- Monorepo setup changes
-- Changes to the docs site/setup
-
-**Note:** For significant changes to public APIs or core architecture, consider writing an [RFC (Request for Comments)](https://github.com/livestorejs/livestore/tree/dev/contributor-docs/rfcs) first to gather feedback before implementation.
-
-### Out of scope (for now)
-
-- Changes to the landing page
-- Changes to the devtools
-- Rewriting the core library in a different language
-
-### Open research questions
-
-- Safer event schema evolution
-- Incremental view maintenance for complex SQLite database views
-
-Please get in touch if you'd like to discuss any of these topics!
-
-## Bug reports
-
-- Please include a [minimal reproducible example](https://stackoverflow.com/help/minimal-reproducible-example) for how to reproduce the bug.
-
-## Guiding principles {#guiding-principles}
-
-- Keep it as simple as possible
-- Reduce surface area
-- Make the right thing easy
-- Document the "why"

package/docs/sustainable-open-source/contributing/monorepo/index.md

@@ -1,195 +0,0 @@
-# Monorepo
-
-## Prerequisites
-
-### Personal experience
-
-Depending on the kind of contribution you're interested in, the following
-experience is recommended:
-
-- Deep experience with TypeScript (incl. type-level programming)
-- Experience with TypeScript monorepo setups
-- Experience with distributed systems
-- Experience with [Effect](https://effect.website) (or willingness to learn)
-
-### Recommended tooling: Use devenv + direnv for a consistent setup
-
-To make development easy and consistent across systems and platforms, this
-project uses [Nix](https://zero-to-nix.com/) with [devenv](https://devenv.sh)
-to manage "system dependencies" such as Node.js, Bun, etc.
-Use [direnv](https://direnv.net) (recommended) to automatically load the
-environment, or run commands explicitly with devenv, for example:
-`devenv shell pnpm install`.
-
-### Manual setup
-
-You'll need to have a recent version the following tools installed:
-
-- Node.js
-- Bun
-- pnpm
-
-## Initial setup
-
-```bash
-git clone git@github.com:livestorejs/livestore.git
-cd livestore
-# Loads env vars, installs deps and builds the project
-./bootstrap.sh
-```
-
-## General notes
-
-- TypeScript
-  - LiveStore tries to follow the strictest TypeScript rules possible to ensure
-    type safety and avoid subtle bugs.
-    - LiveStore also makes heavy use of
-      [TypeScript project references](https://www.typescriptlang.org/docs/handbook/project-references.html).
-- Package management
-  - This project uses [pnpm](https://pnpm.io/) to manage the workspace.
-- LiveStore is primarily developed in VSCode/Cursor.
-- Testing
-  - LiveStore uses Vitest for most tests and Playwright for browser tests.
-
-### Notable used tools / technologies
-
-- [TypeScript](https://www.typescriptlang.org/)
-- [Effect](https://effect.website)
-- [pnpm](https://pnpm.io/)
-- [Bun](https://bun.sh/)
-- [Vitest](https://vitest.dev/)
-- [Playwright](https://playwright.dev/)
-- [OpenTelemetry](https://opentelemetry.io/)
-- [wa-sqlite](https://github.com/rhashimoto/wa-sqlite) (included as git subtree) - see [wa-sqlite management](../../../../../../contributor-docs/wa-sqlite-management.md)
-- [Nix](https://zero-to-nix.com/)
-- [Direnv](https://direnv.net/)
-- [devenv](https://devenv.sh)
-
-### Environment variables
-
-The `.envrc` file contains all necessary environment variables for the project.
-You can create a `.envrc.local` file to override or add variables for your local
-setup. You'll need to run `direnv allow` to load the environment variables.
-
-### VSCode tasks
-
-- This project is primarily developed in VSCode and makes use of
-  [tasks](https://code.visualstudio.com/docs/editor/tasks) to run commands.
-- Common tasks are:
-  - `dev:ts:watch` to run the TypeScript compiler in watch mode for the entire
-    monorepo
-  - `pnpm:install` to install all dependencies (e.g. when changing a
-    `package.json`)
-
-## Tasks to run before committing
-
-Please run the following tasks before committing & pushing:
-
-- `mono ts` to build the TypeScript code
-- `mono lint` to run the linting checks
-- `mono test` to run the tests
-
-## Examples
-
-- Once you've set up the monorepo locally, you'll find all examples in the
-  `/examples` directory.
-- All examples are self-contained and can be run independently.
-- Examples use explicit version dependencies (e.g., `0.3.2-dev.0`) for LiveStore packages.
-- Examples are not part of the monorepo TypeScript build system to maintain independence.
-- Each example has its own TypeScript configuration that's independent of the
-  monorepo build system.
-
-#### Making changes to examples
-
-1. Make your desired changes directly in `/examples/<example-name>`.
-2. Test your changes by running the example (e.g., `pnpm dev` in the example
-   directory).
-3. Commit your changes.
-
-### OpenTelemetry setup
-
-As a local OpenTelemetry setup, we recommend the
-[docker-otel-lgtm](https://github.com/grafana/docker-otel-lgtm) setup.
-
-Add the following to your `.envrc.local` file:
-
-```bash
-export VITE_GRAFANA_ENDPOINT="http://localhost:30003"
-export GRAFANA_ENDPOINT="http://localhost:30003"
-export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
-export VITE_OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
-```
-
-### TypeScript
-
-- Each package has its own `tsconfig.json` file which extends the root
-  `tsconfig.base.json`.
-- This project makes heavy use of TypeScript project references.
-
-### Package management
-
-- This project uses [pnpm](https://pnpm.io/) to manage the workspace.
-- We're using the `workspace:*` protocol to link packages together.
-- We should try to keep dependencies to an absolute minimum and only add them if
-  we absolutely need them.
-- We also need to manually add peer dependencies for each package.
-- We should try to avoid duplicate dependencies across the monorepo as much as
-  possible as duplicate dependencies can lead to a lot of issues and pain.
-  - We're also using the `resolutions` field in the root `package.json` to force
-    some packages to be the same across the monorepo (ideally not needed but for
-    some packages it's necessary currently).
-- We're using [syncpack](https://github.com/JamieMason/syncpack) to help
-  maintain consistent dependency versions across the monorepo.
-  - See `syncpack.config.mjs` for the configuration.
-  - Common commands:
-    - `bunx syncpack format` to format the `package.json` files
-    - `bunx syncpack lint` to check all version ranges
-    - `bunx syncpack fix-mismatches` to adjust versions across `package.json`
-      files (check before with `lint`)
-    - `bunx syncpack update` to update packages across the monorepo to the
-      latest versions
-
-### Notes on external dependencies
-
-LiveStore tries to use as few external dependencies as possible. Given LiveStore
-is built on top of Effect, which can be considered a standard library for
-TypeScript, it should handle most use cases.
-
-#### Notes on some packages
-
-The following packages need to be updated with extra care:
-
-- `react`/`react-dom` as we need to move in lockstep with Expo / React Native
-  (currently pinned to {REACT_VERSION})
-- `effect` (currently pinned to {EFFECT_VERSION})
-
-#### Effect
-
-- LiveStore makes heavy use of the [Effect](https://effect.website) library and
-  ecosystem throughout the implementation of the various packages.
-- Effect is not imposed on the app developers using LiveStore but where it makes
-  sense, LiveStore is also exposing a Effect-based API (e.g. `createStore`).
-
-#### Updating dependencies
-
-- Either update the versions manually in each `package.json` file or use
-  `bunx syncpack update`.
-
-### Notes on monorepo structure
-
-- The `@livestore/utils` package re-exports many common modules/functions (e.g.
-  from `effect`) in order to
-  - Reduce the number of direct dependencies for other packages
-  - Allows for convenient extension of modules (e.g. adding methods to
-    `Effect.___`, `Schema.___`, ...)
-
-## Docs
-
-The LiveStore docs are built with
-[Astro Starlight](https://starlight.astro.build/).
-
-## Related external repos
-
-- [Fork of wa-sqlite](https://github.com/livestorejs/wa-sqlite) with Nix build setup included as git subtree.
-- The source code of the devtools is currently not part of this monorepo but in
-  a separate private repo.

package/docs/sustainable-open-source/sponsoring/index.md

@@ -1,104 +0,0 @@
-# Sponsoring LiveStore
-
-## TLDR
-
-- Sponsoring LiveStore helps ensure long-term stability and improvements for the project you rely on.
-- Sponsors receive exclusive benefits, including a LiveStore Devtools license and access to sponsor-only resources.
-- LiveStore is fully open source and community-supported—your sponsorship directly enables its ongoing development.
-
-<Sponsor />
-
-## Goal: Sustainable Open Source
-
-As the creator and maintainer of LiveStore, I'm often asked *"how do you make money with LiveStore?"*. That's a great question with a simple answer. I'm not building LiveStore to make a lot of money - my goal is to make LiveStore a sustainable open source project. I've been working on LiveStore since 2021 (mostly full-time) and hope you can help to keep the project sustainable.
-
-Open source has been a big part of my life - I've founded [Prisma](https://www.prisma.io/), created [Contentlayer](https://www.contentlayer.dev/), and built/maintained many other open source projects over the years. Through these experiences, I've seen firsthand how challenging it can be to keep open source projects healthy in the long run. Too often, maintainers burn out, and projects that many people depend on end up dying. My goal with LiveStore is to build an open source project that's sustainable and could possibly serve as an inspiration for other open source projects.
-
-I wanted LiveStore to exist for over a decade - something I felt was missing in the ecosystem and that I know others have wanted as well. But building and maintaining a project on that level of ambition is incredibly hard, especially without a clear path to monetization. I believe that's also why a technology like LiveStore didn't exist yet. 
-
-Particularly being concerned about the sustainability of open source projects, I was hesitant to start another open source project myself. Still, I believe deeply in the value LiveStore creates for developers, and I'm committed to making it the best it can be.
-
-The unfortunate reality is that there is no well-established way for open source creators to get paid for their work. While there are some great initiatives and platforms out there - like [Open Source Pledge](https://opensourcepledge.org/), [Generous](https://generous.builders/), [GitHub Sponsors](https://github.com/sponsors), [Polar](https://polar.sh/), [OpenCollective](https://opencollective.com/), and [thanks.dev](https://thanks.dev/) - most open source projects still struggle to capture even a fraction of the value they create. I believe in a positive-sum world, and I'm happy to contribute, but sustainability is essential if LiveStore is going to keep growing and improving.
-
-My mid-/long term goal is to bring in enough resources not just to support myself, but to pay others to work on LiveStore as well. I want to ensure that the project remains stable, well-maintained, and innovative - something you can truly rely on. Sponsorship is the most direct way to make this possible. It's not just about funding features or bug fixes; it's about creating a relationship where your support helps guarantee the future of a tool you depend on.
-
-I hope those words resonate with you and you'll understand why sponsoring LiveStore isn't just a nice gesture - it's essential for keeping the project going and a direct investment in the stability and evolution of a project that your application (and business) depends on. Your support ensures that LiveStore remains sustainable and healthy for the whole community.
-
-Thank you! 🧡
-
-## Related posts
-
-- [The Open Source Sustainability Crisis](https://openpath.quest/2024/the-open-source-sustainability-crisis/) by Chad Whitacre
-- [Entitlement in Open Source](https://mikemcquaid.com/entitlement-in-open-source/) by Homebrew lead Mike McQuaid
-
-## Aligned incentives
-
--	**Stability and Reliability:**
-  Your application depends on LiveStore as the core data foundation. Sponsorship ensures continuous, focused maintenance and improvement, directly benefiting you with increased stability, reliability, and performance.
-
--	**Shared Investment in Long-term Success:**
-  Sponsorship creates mutual investment in the project's future. You sponsoring LiveStore signals that it is crucial to your business, motivating me (and other maintainers) to prioritize features, enhancements, and fixes that benefit you.
-
--	**Avoiding Costly In-House Development:**
-  LiveStore offers a unique architectural design with (currently) no direct alternatives readily available. So the only alternative is building something similar in-house which is takes a lot of time and resources. Sponsorship aligns incentives by ensuring LiveStore remains an attractive and efficient alternative.
-
--	**Transparent Sustainability:**
-  Open-source sustainability is a common challenge as projects stagnate without sustainable resources. Sponsorship transparently addresses this, providing maintainers with clarity and stability, ensuring the project thrives and evolves to users' benefit.
-
--	**Healthy Community and Ecosystem**:
-  Sponsors actively contribute to fostering a healthy, collaborative ecosystem. Their direct involvement ensures responsiveness to real-world needs, creating an ongoing, beneficial dialogue between users and maintainers.
-
--	**Focused Innovation and Quality**:
-  Regular sponsorship allows maintainers to allocate dedicated time to innovative research and high-quality development. This ultimately translates into more reliable software, fewer bugs, faster releases, and thoughtful features driven by actual user needs.
-
--	**Ensuring Longevity and Avoiding Lock-In**:
-  By aligning financial incentives through sponsorship, maintainers avoid being forced into less favorable monetization methods (e.g., restrictive licensing or heavy commercial lock-ins), maintaining open access and flexibility for users.
-
-## Sponsor benefits
-
-You can access your sponsor benefits via the [Sponsor dashboard](https://livestore.dev/sponsor).
-
-- [LiveStore Devtools](/building-with-livestore/devtools) License
-- Access to
-  - Sponsor-only Discord channels
-  - LiveStore Office Hours
-- Prioritized bug fixes and feature requests
-
-## Thanks to our Sponsors
-
-A big and heartfelt thank you to all our sponsors. Your support has been invaluable and LiveStore wouldn't be where it is without you.
-
-### Partners
-
-- [ElectricSQL](https://www.electricsql.com/)
-- [Netlify](https://www.netlify.com/)
-- [Expo](https://expo.dev/)
-- [Axial](https://axial.work/)
-
-### Individuals
-
-A big thank you to all individual GitHub sponsors! 🧡
-
-## FAQ
-
-### Why not raise VC money for LiveStore?
-
-While raising venture capital for LiveStore might be possible, the challenge lies in building a VC-scale business around LiveStore. My current goal is to make and keep LiveStore sustainable without investor funding. (While I don't rule out this path in the future, it's currently not planned.)
-
-### Why not build a hosting service around LiveStore?
-
-While technically feasible, LiveStore embraces partnerships with other syncing services to create a win-win situation and minimize vendor lock-in for users.
-
-### Are free devtools licenses for students?
-
-Yes, please reach out via Discord.
-
-### Are there other ways to support LiveStore?
-
-Yes, there are many ways to support LiveStore:
-
-- Become a [contributor / maintainer](/sustainable-open-source/contributing/info)
-- Help other community members (e.g. via Discord)
-- Spread the word
-  - Give talks, write blog posts, post on social media, ...
-- Provide feedback (e.g. via GitHub issues or Discord)