Skip to content

docs: refresh readme & add sponsors update workflow #2049

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
CodeDredd merged 1 commit into from
Jul 20, 2026
Merged

docs: refresh readme & add sponsors update workflow #2049

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions .github/workflows/sponsors.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
name: sponsors

on:
workflow_dispatch:
schedule:
# first day of every month
- cron: '0 6 1 * *'

permissions:
contents: write

jobs:
update:
if: github.repository == 'CodeDredd/pinia-orm'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
- run: npm i -g --force corepack && corepack enable
- uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
with:
node-version: 22
cache: "pnpm"

- name: Install dependencies
run: pnpm install

- name: Generate sponsor images
run: pnpm sponsor
env:
SPONSORKIT_GITHUB_TOKEN: ${{ secrets.SPONSORKIT_GITHUB_TOKEN }}
SPONSORKIT_GITHUB_LOGIN: codedredd

- name: Commit updated sponsor images
run: |
git config user.email "gregor@codedredd.de"
git config user.name "Gregor Becker"
git add docs/public/sponsorkit
git diff --cached --quiet && echo "no changes" && exit 0
git commit -m "chore: update sponsors [skip-release]"
git push
94 changes: 60 additions & 34 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,41 +8,67 @@

# Welcome to pinia-orm

> Intuitive, type safe and flexible ORM for Pinia based on [Vuex ORM Next](https://github.com/vuex-orm/vuex-orm-next)
> The intuitive, type safe and flexible ORM for [Pinia](https://pinia.vuejs.org) — normalize relational data in your stores and query it like with an ORM.

- [✨  Release Notes](https://pinia-orm.codedredd.de/changelog)
- [📖  Documentation](https://pinia-orm.codedredd.de)
- [👾  Playground](https://pinia-orm-play.codedredd.de)

## Migration from vuex-orm

You want to migrate from vuex to pinia and with it vuex-orm to pinia-orm but you don't know yet?
Well maybe this table will help you to decide. This comparison is just about facts and current state.

| Features | pinia-orm@v1.4.0 | @vuex-orm/core@0.36.4 | @vuex-orm/core@1.0.0-draft.16 |
|------------------------------------------------------------------------|------------------------------------------------------------| ----------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Bundle Size (Min + GZIP) | [9.9 KB](https://bundlephobia.com/package/pinia-orm@1.4.0) | [16.7 KB](https://bundlephobia.com/package/@vuex-orm/core@0.36.4) | [12.6 KB](https://bundlephobia.com/package/@vuex-orm/core@1.0.0-draft.16) |
| Relations (hasMany, belongsTo, morphOne, hasManyBy, hasOne, morphTo) | ✅ | ✅ | ✅ |
| Relations (morphMany, belongsToMany, hasManyThrough) | ✅ | ✅ | ❌ |
| Relations (morphToMany, morphedByMany) | ❌ | ✅ | ❌ |
| Mutators | ✅ | ✅ | ❌ |
| Casts | ✅ | ❌ | ❌ |
| Decorators | ✅ | ❌ | ✅ |
| Single Table Inheritance | ✅ | ✅ | ❌ |
| Lifecycle Hooks | ✅ | ✅ | ❌ |
| Aggregates | ✅ | ✅ | ❌ |
| Query (orHas, doesntHave, orDoesntHave, whereHas, orWhereHas, groupBy) | ✅ | ❌ | ❌ |
| Collection Helpers | ✅ | (✅) can use pinia-orm helpers too | (✅) can use pinia-orm helpers too |
| Hidden Fields | ✅ | ❌ | ❌ |
| Metadata field | ✅ | ❌ | ❌ |
| Caching of queries with gc | ✅ | (✅) with plugin | ❌ |

If you decide to migrate then there are some breaking changes. A guide how to migrate will be written.
Small overview:

- Fields are by default `null`
- Renamed some functions aligning more with laravel naming
- Code is based on `vuex-orm-next` and not on `vuex-orm` !
## Features

- Laravel-style query builder — `where`, `whereLike`, `whereHas`, `orderBy` (incl. `Intl.Collator`), `groupBy`, aggregates, `updateOrCreate` / `firstOrCreate` and more
- All the relations: `hasOne`, `hasMany`, `belongsTo`, `belongsToMany`, `hasManyThrough`, `morphOne`, `morphTo`, `morphMany`, `morphToMany`, `morphedByMany`
- Standard [ECMAScript decorators](https://pinia-orm.codedredd.de/guide/getting-started/typescript) for type safe model definitions
- Single Table Inheritance with nested discriminators, lifecycle hooks, mutators, casts, hidden fields and query caching
- First class [Nuxt module](https://pinia-orm.codedredd.de/guide/nuxt/setup) (Nuxt 3 & 4) and an [axios plugin](https://pinia-orm.codedredd.de/plugins/axios/guide/setup)

## Quick start

```bash
npm install pinia pinia-orm
```

```ts
import { createPinia } from 'pinia'
import { createORM } from 'pinia-orm'

const pinia = createPinia().use(createORM())
```

```ts
import { Model, useRepo } from 'pinia-orm'
import { Attr, HasMany, Str, Uid } from 'pinia-orm/decorators'

class Todo extends Model {
static entity = 'todos'

@Uid() id!: string
@Str('') text!: string
@Attr(null) userId!: string | null
}

class User extends Model {
static entity = 'users'

@Uid() id!: string
@Str('') name!: string
@HasMany(() => Todo, 'userId') todos!: Todo[]
}

const userRepo = useRepo(User)

userRepo.save({ id: '1', name: 'John', todos: [{ text: 'Read the docs' }] })
const usersWithTodos = userRepo.with('todos').get()
```

Read the [documentation](https://pinia-orm.codedredd.de) for the full guide, or check the [comparison with vuex-orm](https://pinia-orm.codedredd.de/guide/getting-started/what-is-pinia-orm#comparison-with-vuex-orm) and the [migration guide](https://pinia-orm.codedredd.de/guide/getting-started/migration-guide) if you're upgrading.

## Requirements

| pinia-orm | pinia | Node | TypeScript |
|-----------|---------|----------|------------|
| 2.x | >= 3 | >= 22.12 | >= 5.2 |
| 1.x | 2.x | >= 14 | >= 4.x |

## Help me keep working on this project 💚

Expand All @@ -60,10 +86,10 @@ Small overview:
## 💻 Development

- Clone this repository
- Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable` (use `npm i -g corepack` for Node.js < 16.10)
- Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable`
- Install dependencies using `pnpm install`
- Build normalizr package: `pnpm build`
- Run interactive tests using `cd packages/pinia-orm && pnpm test:ui`
- Build the packages once with `pnpm build:stub && pnpm build:ci`
- Run tests using `pnpm test` (or `cd packages/pinia-orm && pnpm test:ui` for the interactive UI)

## Credits

Expand All @@ -80,7 +106,7 @@ Small overview:

Made with ❤️

Published under [MIT License](./LICENCE).
Published under [MIT License](./LICENSE).

<!-- Badges -->

Expand Down
28 changes: 28 additions & 0 deletions docs/content/1.guide/1.getting-started/3.what-is-pinia-orm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -264,4 +264,32 @@ const posts = useRepo(Post).query().with('author').where('id', 1).get()
*/
```

## Comparison with Vuex ORM

Coming from vuex-orm and undecided about migrating? This comparison is just about facts and current state.

| Features | pinia-orm@v2 | @vuex-orm/core@0.36.4 | @vuex-orm/core@1.0.0-draft.16 |
|------------------------------------------------------------------------|-------------------------------------------------------|-------------------------------------------------------------------|---------------------------------------------------------------------------|
| Bundle Size (Min + Brotli) | [~16 KB](https://bundlephobia.com/package/pinia-orm) | [16.7 KB](https://bundlephobia.com/package/@vuex-orm/core@0.36.4) | [12.6 KB](https://bundlephobia.com/package/@vuex-orm/core@1.0.0-draft.16) |
| Relations (hasMany, belongsTo, morphOne, hasManyBy, hasOne, morphTo) | ✅ | ✅ | ✅ |
| Relations (morphMany, belongsToMany, hasManyThrough) | ✅ | ✅ | ❌ |
| Relations (morphToMany, morphedByMany) | ✅ | ✅ | ❌ |
| Mutators | ✅ | ✅ | ❌ |
| Casts | ✅ | ❌ | ❌ |
| Standard ECMAScript decorators | ✅ | ❌ | ❌ |
| Single Table Inheritance (incl. nested discriminators) | ✅ | ✅ | ❌ |
| Lifecycle Hooks | ✅ | ✅ | ❌ |
| Aggregates | ✅ | ✅ | ❌ |
| Query (orHas, doesntHave, whereHas, whereLike, groupBy, ...) | ✅ | ❌ | ❌ |
| Collection Helpers | ✅ | (✅) can use pinia-orm helpers too | (✅) can use pinia-orm helpers too |
| Hidden Fields | ✅ | ❌ | ❌ |
| Metadata field | ✅ | ❌ | ❌ |
| Caching of queries with gc | ✅ | (✅) with plugin | ❌ |

If you decide to migrate, check the [migration guide](migration-guide) for the current breaking changes. The most notable differences to vuex-orm:

- Fields are by default `null`
- Some functions are renamed to align more with the laravel naming
- The code base originates from `vuex-orm-next`, not `vuex-orm`

Cool, isn't it? Are you ready to start using Pinia ORM? [Let's get started](quick-start).
Loading