0
# Pinia Instance Management
1

2
Core functions for creating and managing the global Pinia instance that coordinates all stores in your application.
3

4
## Capabilities
5

6
### Create Pinia Instance
7

8
Creates a new Pinia instance to be used by the application. This is typically done once at the application root level.
9

10
```typescript { .api }
11
/**
12
 * Creates a Pinia instance to be used by the application
13
 * @returns A new Pinia instance with plugin system and state management
14
 */
15
function createPinia(): Pinia;
16

17
interface Pinia {
18
  /** Vue plugin install method */
19
  install(app: App): void;
20
  /** Add a plugin to extend Pinia's functionality */
21
  use(plugin: PiniaPlugin): Pinia;
22
  /** Reactive state container for all stores */
23
  state: Ref<Record<string, StateTree>>;
24
  /** Array of installed plugins */
25
  _p: PiniaPlugin[];
26
  /** Reference to the Vue app instance */
27
  _a: App | null;
28
  /** Effect scope for reactivity cleanup */
29
  _e: EffectScope;
30
  /** Map of all store instances */
31
  _s: Map<string, StoreGeneric>;
32
}
33
```
34

35
**Usage Examples:**
36

37
```typescript
38
import { createApp } from "vue";
39
import { createPinia } from "pinia";
40

41
const app = createApp({});
42
const pinia = createPinia();
43

44
// Install Pinia as a Vue plugin
45
app.use(pinia);
46

47
// Add plugins before or after installation
48
pinia.use(myCustomPlugin);
49
```
50

51
### Dispose Pinia Instance
52

53
Disposes of a Pinia instance by stopping its effect scope and removing the state, plugins, and stores. Useful for testing and applications with multiple Pinia instances.
54

55
```typescript { .api }
56
/**
57
 * Dispose a Pinia instance by stopping its effectScope and removing the state, plugins and stores
58
 * @param pinia - Pinia instance to dispose
59
 */
60
function disposePinia(pinia: Pinia): void;
61
```
62

63
**Usage Examples:**
64

65
```typescript
66
import { createPinia, disposePinia } from "pinia";
67

68
const pinia = createPinia();
69

70
// Later, clean up the instance
71
disposePinia(pinia);
72

73
// The pinia instance cannot be used anymore after disposal
74
```
75

76
### Set Active Pinia
77

78
Sets the active Pinia instance. This allows calling `useStore()` outside of a component setup after installing Pinia's plugin.
79

80
```typescript { .api }
81
/**
82
 * Sets the active pinia instance
83
 * @param pinia - Pinia instance to set as active
84
 */
85
function setActivePinia(pinia: Pinia): void;
86
```
87

88
**Usage Examples:**
89

90
```typescript
91
import { createPinia, setActivePinia, defineStore } from "pinia";
92

93
const pinia = createPinia();
94
setActivePinia(pinia);
95

96
// Now you can use stores outside of Vue components
97
const useStore = defineStore("main", () => ({ count: ref(0) }));
98
const store = useStore(); // Works outside of component setup
99
```
100

101
### Get Active Pinia
102

103
Gets the currently active Pinia instance, if any.
104

105
```typescript { .api }
106
/**
107
 * Gets the currently active pinia instance
108
 * @returns The active Pinia instance or undefined if none is set
109
 */
110
function getActivePinia(): Pinia | undefined;
111
```
112

113
**Usage Examples:**
114

115
```typescript
116
import { getActivePinia } from "pinia";
117

118
const currentPinia = getActivePinia();
119

120
if (currentPinia) {
121
  // Use the active pinia instance
122
  console.log("Active Pinia found");
123
} else {
124
  console.log("No active Pinia instance");
125
}
126
```
127

128
## Plugin System
129

130
### Pinia Plugin
131

132
Plugins extend Pinia's functionality and receive a context object with access to the Pinia instance, Vue app, current store, and store options.
133

134
```typescript { .api }
135
type PiniaPlugin = (context: PiniaPluginContext) => Partial<PiniaCustomProperties & PiniaCustomStateProperties> | void;
136

137
interface PiniaPluginContext<Id extends string = string, S extends StateTree = {}, G = {}, A = {}> {
138
  /** The Pinia instance */
139
  pinia: Pinia;
140
  /** The Vue app instance */
141
  app: App;
142
  /** The current store being processed */
143
  store: Store<Id, S, G, A>;
144
  /** The store options passed to defineStore */
145
  options: DefineStoreOptionsInPlugin<Id, S, G, A>;
146
}
147

148
interface PiniaCustomProperties {}
149
interface PiniaCustomStateProperties {}
150
```
151

152
**Usage Examples:**
153

154
```typescript
155
import { PiniaPluginContext } from "pinia";
156

157
// Plugin that adds a custom method to all stores
158
const customPlugin = ({ store }: PiniaPluginContext) => {
159
  return {
160
    customMethod() {
161
      console.log(`Called from store: ${store.$id}`);
162
    },
163
  };
164
};
165

166
// Plugin that adds state properties
167
const statePlugin = ({ store }: PiniaPluginContext) => {
168
  store.$state.createdAt = new Date();
169
};
170

171
// Use the plugins
172
pinia.use(customPlugin);
173
pinia.use(statePlugin);
174
```
175

176
## Types
177

178
```typescript { .api }
179
interface DefineStoreOptionsInPlugin<Id extends string, S extends StateTree, G, A> {
180
  id: Id;
181
  state?: () => S;
182
  getters?: G;
183
  actions?: A;
184
  hydrate?(storeState: UnwrapRef<S>, initialState: UnwrapRef<S>): void;
185
}
186

187
type StoreGeneric = Store<string, StateTree, Record<string, any>, Record<string, any>>;
188
```