Quick start

Prologue

Note that in this documentation, we borrow many examples and texts from Vuex ORM Next. We would like to credit Vuex ORM Next and the author of the section Kia King Ishii for the awesome work.

This is a quick starting guide to begin using Pinia ORM. It assumes you have a basic understanding of Pinia. If you are not familiar with Pinia, please visit the Pinia Documentation to learn more.

Setup

To setup Pinia ORM, you must:

• Install Pinia ORM to Pinia.
• Define Models.

Don't worry. It's much easier than you think.

Install Pinia ORM

yarn add pinia-orm

npm install pinia-orm --save

pnpm add pinia-orm

Adding the plugin to your pinia store

import { createPinia } from 'pinia'
import { createORM } from 'pinia-orm'
const pinia = createPinia().use(createORM())

import { createPinia, PiniaVuePlugin } from 'pinia'
import { createORM } from 'pinia-orm'
Vue.use(PiniaVuePlugin)
const pinia = createPinia().use(createORM())

Define models

Models represent a schema of data that will be stored in Pinia. The schema often follows a servers API response, but it could also be whatever you like it to be.

Models may have relationships with other models. For example, a post could belong to a user, or a post has many comments.

The following examples will demonstrate what these models may look like:

User Model

// User Model
import { Model } from 'pinia-orm'
export default class User extends Model {
  // entity is a required property for all models.
  static entity = 'users'
  // List of all fields (schema) of the post model. `this.string()` declares
  // a string field type with a default value as the first argument.
  // `this.uid()` declares a unique id if none provided.
  static fields () {
    return {
      id: this.uid(),
      name: this.string(''),
      email: this.string('')
    }
  }
  // For typescript support of the field include also the next lines
  declare id: string
  declare name: string
  declare email: string
}

// User Model
import { Model } from 'pinia-orm'
import { Str, Uid } from 'pinia-orm/decorators'
export default class User extends Model {
  // entity is a required property for all models.
  static entity = 'users'
  @Uid() declare id: string
  @Str('') declare name: string
  @Str('') declare email: string
}

Post Model

// Post Model
import { Model } from 'pinia-orm'
import User from './User'
export default class Post extends Model {
  static entity = 'posts'
  // `this.belongsTo(...)` declares this post belongs to a user. The first
  // argument is the `User` model class. The second is the field name for
  // the foreign key `userId`.
  static fields () {
    return {
      id: this.uid(),
      userId: this.attr(null),
      title: this.string(''),
      body: this.string(''),
      published: this.boolean(false),
      author: this.belongsTo(User, 'userId')
    }
  }
  
  declare id: string
  declare userId: string | null
  declare title: string
  declare body: string
  declare published: boolean
  declare author: User | null
}

// Post Model
import { Model } from 'pinia-orm'
import { Attr, BelongsTo, Bool, Str, Uid } from 'pinia-orm/decorators'
import User from './User'
export default class Post extends Model {
  static entity = 'posts'
  @Uid() declare id: string
  @Attr(null) declare userId: string | null
  @Str('') declare title: string
  @Str('') declare body: string
  @Bool(false) declare published: boolean
  @BelongsTo(() => User, 'userId') declare author: User | null
}

All models are declared by extending the Pinia ORM base Model class.

These examples create a User model and a Post model. The Post model has a belongsTo relationship to User defined by the author key. It's now possible to create posts that are associated with users.

You can learn more about models at Model: Getting Started.

You're good to go!

Check out how to use Pinia ORM.

Edge Channel

After each commit is merged into the main branch of pinia-orm and passing all tests, we trigger an automated npm release using Github Actions publishing a pinia-orm-edge package.

This also happens for the other packages @pinia-orm/nuxt-edge, @pinia-orm/normalizr-edge and @pinia-orm/axios-edge.

You can opt in to use this release channel and avoid waiting for the next release and helping the module by beta testing changes.

The build and publishing method and quality of edge releases are the same as stable ones. The only difference is that you should often check the GitHub repository for updates. There is a slight chance of regressions not being caught during the review process and by the automated tests. Therefore, we internally use this channel to double-check everything before each release.

Opting into the edge channel

Update pinia-orm dependency inside package.json:

{
  "devDependencies": {
-   "pinia-orm": "^1.0.0"
+   "pinia-orm": "npm:pinia-orm-edge@latest"
  }
}

Remove lockfile (package-lock.json, yarn.lock, or pnpm-lock.yaml) and reinstall dependencies.

Opting out from the edge channel

Update pinia-orm dependency inside package.json:

{
  "devDependencies": {
-   "pinia-orm": "npm:pinia-orm-edge@latest"
+   "pinia-orm": "^1.0.0"
  }
}

Remove lockfile (package-lock.json, yarn.lock, or pnpm-lock.yaml) and reinstall dependencies.