From: Eduardo San Martin Morote Date: Thu, 3 Jul 2025 19:38:38 +0000 (+0200) Subject: docs: add rulekit X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=31a0c97b0246dcb3d047ab61c3b71cc68dbca6ab;p=thirdparty%2Fvuejs%2Fpinia.git docs: add rulekit --- diff --git a/packages/docs/.vitepress/theme/components/RuleKitLink.vue b/packages/docs/.vitepress/theme/components/RuleKitLink.vue new file mode 100644 index 00000000..ff52d35e --- /dev/null +++ b/packages/docs/.vitepress/theme/components/RuleKitLink.vue @@ -0,0 +1,206 @@ + + + + + diff --git a/packages/docs/.vitepress/theme/index.ts b/packages/docs/.vitepress/theme/index.ts index a205ef14..f67f0606 100644 --- a/packages/docs/.vitepress/theme/index.ts +++ b/packages/docs/.vitepress/theme/index.ts @@ -11,6 +11,7 @@ import './styles/playground-links.css' import VueSchoolLink from './components/VueSchoolLink.vue' import VueMasteryLogoLink from './components/VueMasteryLogoLink.vue' import MasteringPiniaLink from './components/MasteringPiniaLink.vue' +import RuleKitLink from './components/RuleKitLink.vue' import status from '../translation-status.json' const i18nLabels = { @@ -33,6 +34,7 @@ const theme: Theme = { app.component('VueSchoolLink', VueSchoolLink) app.component('VueMasteryLogoLink', VueMasteryLogoLink) app.component('MasteringPiniaLink', MasteringPiniaLink) + app.component('RuleKitLink', RuleKitLink) }, } diff --git a/packages/docs/.vitepress/theme/styles/home-links.css b/packages/docs/.vitepress/theme/styles/home-links.css index 108987fa..b1702c1e 100644 --- a/packages/docs/.vitepress/theme/styles/home-links.css +++ b/packages/docs/.vitepress/theme/styles/home-links.css @@ -99,6 +99,28 @@ a.cta.vueschool::after { border-left: 7px solid currentColor; } +a.cta.rulekit { + font-family: 'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace; +} + +a.cta.rulekit::before { + content: ''; + display: inline-block; + width: 16px; + height: 16px; + background-image: url('/rulekit-logo.svg'); + background-size: 16px; + background-repeat: no-repeat; + background-position: center; + margin-right: 0.5em; + vertical-align: middle; + filter: brightness(0); /* Make it black by default */ +} + +html.dark a.cta.rulekit::before { + filter: brightness(0) invert(1); /* Make it white in dark mode */ +} + @media (max-width: 420px) { a.cta.cta.vue-mastery { max-width: 320px; diff --git a/packages/docs/cookbook/composables.md b/packages/docs/cookbook/composables.md index ab655fe1..6ace86e4 100644 --- a/packages/docs/cookbook/composables.md +++ b/packages/docs/cookbook/composables.md @@ -21,6 +21,8 @@ export const useAuthStore = defineStore('auth', { Keep in mind that **you can only return writable state** (e.g. a `ref()`). Here are some examples of composables that you can use: + + - [useLocalStorage](https://vueuse.org/core/useLocalStorage/) - [useAsyncState](https://vueuse.org/core/useAsyncState/) diff --git a/packages/docs/cookbook/composing-stores.md b/packages/docs/cookbook/composing-stores.md index 44894f8d..de89b99b 100644 --- a/packages/docs/cookbook/composing-stores.md +++ b/packages/docs/cookbook/composing-stores.md @@ -1,5 +1,7 @@ # Composing Stores + + Composing stores is about having stores that use each other, and this is supported in Pinia. There is one rule to follow: If **two or more stores use each other**, they cannot create an infinite loop through _getters_ or _actions_. They cannot **both** directly read each other state in their setup function: diff --git a/packages/docs/cookbook/hot-module-replacement.md b/packages/docs/cookbook/hot-module-replacement.md index af5d6bd5..3ec95340 100644 --- a/packages/docs/cookbook/hot-module-replacement.md +++ b/packages/docs/cookbook/hot-module-replacement.md @@ -1,5 +1,7 @@ # HMR (Hot Module Replacement) + + Pinia supports Hot Module replacement so you can edit your stores and interact with them directly in your app without reloading the page, allowing you to keep the existing state, add, or even remove state, actions, and getters. At the moment, only [Vite](https://vitejs.dev/guide/api-hmr.html#hmr-api) is officially supported but any bundler implementing the `import.meta.hot` spec should work (e.g. [webpack](https://webpack.js.org/api/module-variables/#importmetawebpackhot) seems to use `import.meta.webpackHot` instead of `import.meta.hot`). diff --git a/packages/docs/cookbook/index.md b/packages/docs/cookbook/index.md index 0bdf9a5e..5bad5194 100644 --- a/packages/docs/cookbook/index.md +++ b/packages/docs/cookbook/index.md @@ -1,5 +1,7 @@ # Cookbook + + - [Migrating from Vuex ≤4](./migration-vuex.md): A migration guide for converting Vuex ≤4 projects. - [HMR](./hot-module-replacement.md): How to activate hot module replacement and improve the developer experience. - [Testing Stores (WIP)](./testing.md): How to unit test Stores and mock them in component unit tests. diff --git a/packages/docs/cookbook/migration-v1-v2.md b/packages/docs/cookbook/migration-v1-v2.md index 457969fa..e502fbac 100644 --- a/packages/docs/cookbook/migration-v1-v2.md +++ b/packages/docs/cookbook/migration-v1-v2.md @@ -1,5 +1,7 @@ # Migrating from 0.x (v1) to v2 + + Starting at version `2.0.0-rc.4`, pinia supports both Vue 2 and Vue 3! This means, all new updates will be applied to this version 2 so both Vue 2 and Vue 3 users can benefit from it. If you are using Vue 3, this doesn't change anything for you as you were already using the rc and you can check [the CHANGELOG](https://github.com/vuejs/pinia/blob/v2/packages/pinia/CHANGELOG.md) for a detailed explanation of everything that changed. Otherwise, **this guide is for you**! ## Deprecations diff --git a/packages/docs/cookbook/migration-v2-v3.md b/packages/docs/cookbook/migration-v2-v3.md index 3f244874..d347bc61 100644 --- a/packages/docs/cookbook/migration-v2-v3.md +++ b/packages/docs/cookbook/migration-v2-v3.md @@ -1,5 +1,7 @@ # Migrating from v2 to v3 + + Pinia v3 is a _boring_ major release with no new features. It drops deprecated APIs and updates major dependencies. It only supports Vue 3. If you are using Vue 2, you can keep using v2. If you need help, [book help with Pinia's author](https://cal.com/posva/consultancy). For most users, the migration should require **no change**. This guide is here to help you in case you encounter any issues. diff --git a/packages/docs/cookbook/migration-vuex.md b/packages/docs/cookbook/migration-vuex.md index a388652c..5919dc21 100644 --- a/packages/docs/cookbook/migration-vuex.md +++ b/packages/docs/cookbook/migration-vuex.md @@ -14,6 +14,8 @@ The easiest way to transition that concept to be used with Pinia is that each mo How you choose to restructure your Vuex modules into Pinia stores is entirely up to you, but here is one suggestion: + + ```bash # Vuex example (assuming namespaced modules) src diff --git a/packages/docs/cookbook/options-api.md b/packages/docs/cookbook/options-api.md index 6c352f72..20d70468 100644 --- a/packages/docs/cookbook/options-api.md +++ b/packages/docs/cookbook/options-api.md @@ -8,6 +8,8 @@ Pinia can be used even if you are not using the composition API (if you are usin - ⚠️ [mapGetters](../core-concepts/getters.md#without-setup) (just for migration convenience, use `mapState()` instead) - [mapActions](../core-concepts/actions.md#without-setup) + + ## Giving access to the whole store If you need to access pretty much everything from the store, it might be too much to map every single property of the store... Instead you can get access to the whole store with `mapStores()`: diff --git a/packages/docs/cookbook/testing.md b/packages/docs/cookbook/testing.md index 3eab75d9..4c1a2a0f 100644 --- a/packages/docs/cookbook/testing.md +++ b/packages/docs/cookbook/testing.md @@ -13,6 +13,8 @@ Stores will, by design, be used at many places and can make testing much harder Depending on what or how you are testing, we need to take care of these three things differently. + + ## Unit testing a store To unit test a store, the most important part is creating a `pinia` instance: diff --git a/packages/docs/cookbook/vscode-snippets.md b/packages/docs/cookbook/vscode-snippets.md index 18331952..334f0f29 100644 --- a/packages/docs/cookbook/vscode-snippets.md +++ b/packages/docs/cookbook/vscode-snippets.md @@ -1,5 +1,7 @@ # VS Code Snippets + + These are some snippets that I use in VS Code to make my life easier. Manage user snippets with ⇧ Shift+⌘ Command+P / ⇧ Shift+⌃ Control+P and then `Snippets: Configure User Snippets`. diff --git a/packages/docs/core-concepts/actions.md b/packages/docs/core-concepts/actions.md index c795219b..a15b9218 100644 --- a/packages/docs/core-concepts/actions.md +++ b/packages/docs/core-concepts/actions.md @@ -29,6 +29,8 @@ export const useCounterStore = defineStore('counter', { }) ``` + + Like [getters](./getters.md), actions get access to the _whole store instance_ through `this` with **full typing (and autocompletion ✨) support**. **Unlike getters, `actions` can be asynchronous**, you can `await` inside of actions any API call or even other actions! Here is an example using [Mande](https://github.com/posva/mande). Note the library you use doesn't matter as long as you get a `Promise`. You could even use the native `fetch` function (browser only): ```js diff --git a/packages/docs/core-concepts/getters.md b/packages/docs/core-concepts/getters.md index 4942c7ba..f1a9fc10 100644 --- a/packages/docs/core-concepts/getters.md +++ b/packages/docs/core-concepts/getters.md @@ -23,6 +23,8 @@ export const useCounterStore = defineStore('counter', { }) ``` + + Most of the time, getters will only rely on the state. However, they might need to use other getters. Because of this, we can get access to the _whole store instance_ through `this` when defining a regular function **but it is necessary to define the type of the return type (in TypeScript)**. This is due to a known limitation in TypeScript and **doesn't affect getters defined with an arrow function nor getters not using `this`**: ```ts diff --git a/packages/docs/core-concepts/index.md b/packages/docs/core-concepts/index.md index 49c2350c..f3cc3eee 100644 --- a/packages/docs/core-concepts/index.md +++ b/packages/docs/core-concepts/index.md @@ -29,6 +29,8 @@ This _name_, also referred to as _id_, is necessary and is used by Pinia to conn `defineStore()` accepts two distinct values for its second argument: a Setup function or an Options object. + + ## Option Stores Similar to Vue's Options API, we can also pass an Options Object with `state`, `actions`, and `getters` properties. diff --git a/packages/docs/core-concepts/outside-component-usage.md b/packages/docs/core-concepts/outside-component-usage.md index 97ddc53e..97bb7ee8 100644 --- a/packages/docs/core-concepts/outside-component-usage.md +++ b/packages/docs/core-concepts/outside-component-usage.md @@ -10,6 +10,8 @@ Pinia stores rely on the `pinia` instance to share the same store instance acros Behind the scenes, `useStore()` _injects_ the `pinia` instance you gave to your `app`. This means that if the `pinia` instance cannot be automatically injected, you have to manually provide it to the `useStore()` function. You can solve this differently depending on the kind of application you are writing. + + ## Single Page Applications If you are not doing any SSR (Server Side Rendering), any call of `useStore()` after installing the pinia plugin with `app.use(pinia)` will work: diff --git a/packages/docs/core-concepts/plugins.md b/packages/docs/core-concepts/plugins.md index 02379bd3..3ecff4d0 100644 --- a/packages/docs/core-concepts/plugins.md +++ b/packages/docs/core-concepts/plugins.md @@ -15,6 +15,8 @@ Pinia stores can be fully extended thanks to a low level API. Here is a list of - Implement side effects like [Local Storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) - Apply **only** to specific stores + + Plugins are added to the pinia instance with `pinia.use()`. The simplest example is adding a static property to all stores by returning an object: ```js diff --git a/packages/docs/core-concepts/state.md b/packages/docs/core-concepts/state.md index a0bacc5a..4421f770 100644 --- a/packages/docs/core-concepts/state.md +++ b/packages/docs/core-concepts/state.md @@ -36,6 +36,8 @@ In order for Vue to properly detect state, you must declare every state piece in ::: + + ## TypeScript You don't need to do much in order to make your state compatible with TS: make sure [`strict`](https://www.typescriptlang.org/tsconfig#strict), or at the very least, [`noImplicitThis`](https://www.typescriptlang.org/tsconfig#noImplicitThis), is enabled and Pinia will infer the type of your state automatically! However, there are a few cases where you should give it a hand with some casting: diff --git a/packages/docs/getting-started.md b/packages/docs/getting-started.md index 57566cf6..25197234 100644 --- a/packages/docs/getting-started.md +++ b/packages/docs/getting-started.md @@ -52,6 +52,8 @@ app.mount('#app') A Store (like Pinia) is an entity holding state and business logic that isn't bound to your Component tree. In other words, **it hosts global state**. It's a bit like a component that is always there and that everybody can read off and write to. It has **three concepts**, the [state](./core-concepts/state.md), [getters](./core-concepts/getters.md) and [actions](./core-concepts/actions.md) and it's safe to assume these concepts are the equivalent of `data`, `computed` and `methods` in components. + + ## When should I use a Store A store should contain data that can be accessed throughout your application. This includes data that is used in many places, e.g. User information that is displayed in the navbar, as well as data that needs to be preserved through pages, e.g. a very complicated multi-step form. diff --git a/packages/docs/index.md b/packages/docs/index.md index 4661bf0b..a7f8fbc7 100644 --- a/packages/docs/index.md +++ b/packages/docs/index.md @@ -18,6 +18,9 @@ hero: - theme: alt text: Demo link: https://stackblitz.com/github/piniajs/example-vue-3-vite + - theme: cta rulekit + text: RuleKit + link: https://rulekit.dev?from=vuerouter - theme: cta mastering-pinia text: ' ' link: https://masteringpinia.com diff --git a/packages/docs/introduction.md b/packages/docs/introduction.md index 7092e98c..902948b1 100644 --- a/packages/docs/introduction.md +++ b/packages/docs/introduction.md @@ -35,6 +35,8 @@ Pinia is a store library for Vue, it allows you to share a state across componen If you still have doubts, check out [the **official** Mastering Pinia course](https://masteringpinia.com). In the beginning we cover how to build our own `defineStore()` function and then we move to the official Pinia API. + + diff --git a/packages/docs/public/rulekit-logo.svg b/packages/docs/public/rulekit-logo.svg new file mode 100644 index 00000000..f20d6178 --- /dev/null +++ b/packages/docs/public/rulekit-logo.svg @@ -0,0 +1,6 @@ + + + + + + \ No newline at end of file diff --git a/packages/docs/ssr/index.md b/packages/docs/ssr/index.md index 4eac7dcc..4843a252 100644 --- a/packages/docs/ssr/index.md +++ b/packages/docs/ssr/index.md @@ -19,6 +19,8 @@ const main = useMainStore() ``` + + ## Using the store outside of `setup()` If you need to use the store somewhere else, you need to pass the `pinia` instance [that was passed to the app](../getting-started.md#installation) to the `useStore()` function call: diff --git a/packages/docs/ssr/nuxt.md b/packages/docs/ssr/nuxt.md index 2a78d672..f65e9dba 100644 --- a/packages/docs/ssr/nuxt.md +++ b/packages/docs/ssr/nuxt.md @@ -7,6 +7,8 @@ Using Pinia with [Nuxt](https://nuxt.com/) is easier since Nuxt takes care of a lot of things when it comes to _server side rendering_. For instance, **you don't need to care about serialization nor XSS attacks**. Pinia supports Nuxt Bridge and Nuxt 3. For bare Nuxt 2 support, [see below](#nuxt-2-without-bridge). + + ## Installation ```bash diff --git a/packages/docs/zh/cookbook/composables.md b/packages/docs/zh/cookbook/composables.md index b8b6cd88..371e959c 100644 --- a/packages/docs/zh/cookbook/composables.md +++ b/packages/docs/zh/cookbook/composables.md @@ -1,5 +1,7 @@ # 处理组合式函数 %{#dealing-with-composables}% + + [组合式函数](https://cn.vuejs.org/guide/reusability/composables.html#composables)是利用 Vue 组合式 API 来封装和复用有状态逻辑的函数。无论你是自己写，还是使用[外部库](https://vueuse.org/)，或者两者都有，你都可以在 pinia store 中充分发挥组合式函数的力量。 ## Option Stores %{#option-stores}% diff --git a/packages/docs/zh/cookbook/composing-stores.md b/packages/docs/zh/cookbook/composing-stores.md index 90ac2fa9..b07d3673 100644 --- a/packages/docs/zh/cookbook/composing-stores.md +++ b/packages/docs/zh/cookbook/composing-stores.md @@ -1,5 +1,7 @@ # 组合式 Store %{#composing-stores}% + + 组合式 store 是可以相互使用，Pinia 当然也支持它。但有一个规则需要遵循： 如果**两个或更多的 store 相互使用**，它们不可以通过 _getters_ 或 _actions_ 创建一个无限循环。它们也不可以**同时**在它们的 setup 函数中直接互相读取对方的 state： diff --git a/packages/docs/zh/cookbook/hot-module-replacement.md b/packages/docs/zh/cookbook/hot-module-replacement.md index 68a9a671..76a959ec 100644 --- a/packages/docs/zh/cookbook/hot-module-replacement.md +++ b/packages/docs/zh/cookbook/hot-module-replacement.md @@ -1,5 +1,7 @@ # HMR (Hot Module Replacement) %{#hmr-hot-module-replacement}% + + Pinia 支持热更新，所以你可以编辑你的 store，并直接在你的应用中与它们互动，而不需要重新加载页面，允许你保持当前的 state、并添加甚至删除 state、action 和 getter。 目前，只有 [Vite](https://cn.vitejs.dev/guide/api-hmr#hmr-api) 被官方支持，不过任何实现 `import.meta.hot` 规范的构建工具都应该能正常工作。(例外的是，[webpack](https://webpack.js.org/api/module-variables/#importmetawebpackhot) 似乎使用的是 `import.meta.webpackHot` 而不是 `import.meta.hot` ) diff --git a/packages/docs/zh/cookbook/index.md b/packages/docs/zh/cookbook/index.md index 22c9b315..a7bd99e4 100644 --- a/packages/docs/zh/cookbook/index.md +++ b/packages/docs/zh/cookbook/index.md @@ -1,5 +1,7 @@ # 手册 %{#cookbook}% + + - [从 Vuex ≤4 迁移](./migration-vuex.md)。用于转换 Vuex ≤4 项目的迁移指南。 - [HMR](./hot-module-replacement.md)：如何激活热更新并改善开发者体验。 - [测试 Stores (WIP)](./testing.md): 如何对 Store 进行单元测试并在组件单元测试中模拟它们。 diff --git a/packages/docs/zh/cookbook/migration-v1-v2.md b/packages/docs/zh/cookbook/migration-v1-v2.md index 3f3cb089..22cd9332 100644 --- a/packages/docs/zh/cookbook/migration-v1-v2.md +++ b/packages/docs/zh/cookbook/migration-v1-v2.md @@ -1,5 +1,7 @@ # 从 0.x (v1) 迁移至 v2 %{#migrating-from-0-x-v1-to-v2}% + + 从 `2.0.0-rc.4` 版本开始，pinia 同时支持 Vue 2 和 Vue 3！这意味着，v2 版本的所有更新，将会让 Vue 2 和 Vue 3 的用户都受益。如果你使用的是 Vue 3，这对你来说没有任何改变，因为你已经在使用 rc 版本，你可以查看[发布日志](https://github.com/vuejs/pinia/blob/v2/packages/pinia/CHANGELOG.md)来了解所有更新的详细解释。如果你使用的不是 Vue 3，**那这个指南是为你准备的**! ## 弃用 %{#deprecations}% diff --git a/packages/docs/zh/cookbook/migration-vuex.md b/packages/docs/zh/cookbook/migration-vuex.md index bae87804..50f42477 100644 --- a/packages/docs/zh/cookbook/migration-vuex.md +++ b/packages/docs/zh/cookbook/migration-vuex.md @@ -1,5 +1,7 @@ # 从 Vuex ≤4 迁移 %{#migrating-from-vuex-≤4}% + + 虽然 Vuex 和 Pinia store 的结构不同，但很多逻辑都可以复用。本指南的作用是帮助你完成迁移，并指出一些可能出现的常见问题。 ## 准备 %{#preparation}% diff --git a/packages/docs/zh/cookbook/options-api.md b/packages/docs/zh/cookbook/options-api.md index 3142cafe..5b210bfd 100644 --- a/packages/docs/zh/cookbook/options-api.md +++ b/packages/docs/zh/cookbook/options-api.md @@ -1,5 +1,7 @@ # 不使用 `setup()` 的用法 %{#usage-without-setup}% + + 即使你没有使用组合式 API，也可以使用 Pinia(如果你使用 Vue 2，你仍然需要安装 `@vue/composition-api` 插件)。虽然我们推荐你试着学习一下组合式 API，但对你和你的团队来说目前可能还不是时候，你可能正在迁移一个应用，或者有其他原因。你可以试试下面几个函数： - [mapStores](#giving-access-to-the-whole-store) diff --git a/packages/docs/zh/cookbook/testing.md b/packages/docs/zh/cookbook/testing.md index 01d3d0cb..810e3a66 100644 --- a/packages/docs/zh/cookbook/testing.md +++ b/packages/docs/zh/cookbook/testing.md @@ -1,5 +1,7 @@ # store 测试 %{#testing-stores}% + + + 有一些代码片段可以让你在 VS Code 中更轻松地使用 Pinia。 通过 ⇧ ⌘ P / ⇧ ⌃ P 然后输入 `Snippets: Configure User Snippets` 就可以管理用户代码片段。 diff --git a/packages/docs/zh/core-concepts/actions.md b/packages/docs/zh/core-concepts/actions.md index 59bfaa69..778fd66d 100644 --- a/packages/docs/zh/core-concepts/actions.md +++ b/packages/docs/zh/core-concepts/actions.md @@ -1,5 +1,7 @@ # Action %{#actions}% + +