docs: port typescript tutorial to Vue docs

Author: crutchcorn

docs/tutorials/typescript.md

@@ -0,0 +1,167 @@
+---
+id: typescript-quick-start
+title: TypeScript Quick Start
+sidebar_label: TypeScript Quick Start
+hide_title: true
+---
+
+ 
+
+# Vue Redux TypeScript Quick Start
+
+:::tip What You'll Learn
+
+- How to set up and use Redux Toolkit and Vue Redux with TypeScript
+
+:::
+
+:::info Prerequisites
+
+- Knowledge of Vue's [Composition API](https://vuejs.org/guide/extras/composition-api-faq.html)
+- Understanding of [Redux terms and concepts](https://redux.js.org/tutorials/fundamentals/part-2-concepts-data-flow)
+- Understanding of TypeScript syntax and concepts
+
+:::
+
+## Introduction
+
+Welcome to the Vue Redux TypeScript Quick Start tutorial! **This tutorial will briefly show how to use TypeScript with Redux Toolkit and Vue-Redux**.
+
+This page focuses on just how to set up the TypeScript aspects. For explanations of what Redux is, how it works, and full examples of how to use Redux, see [the Redux core docs tutorials](https://redux.js.org/tutorials/index).
+
+[Vue Redux](/) is also written in TypeScript, and also includes its own type definitions.
+
+## Project Setup
+
+### Define Root State and Dispatch Types
+
+[Redux Toolkit's `configureStore` API](https://redux-toolkit.js.org/api/configureStore) should not need any additional typings. You will, however, want to extract the `RootState` type and the `Dispatch` type so that they can be referenced as needed. Inferring these types from the store itself means that they correctly update as you add more state slices or modify middleware settings.
+
+Since those are types, it's safe to export them directly from your store setup file such as `app/store.ts` and import them directly into other files.
+
+```ts title="app/store.ts"
+import { configureStore } from "@reduxjs/toolkit";
+// ...
+
+const store = configureStore({
+  reducer: {
+    posts: postsReducer,
+    comments: commentsReducer,
+    users: usersReducer,
+  },
+});
+
+// highlight-start
+// Infer the `RootState` and `AppDispatch` types from the store itself
+export type RootState = ReturnType<typeof store.getState>;
+// Inferred type: {posts: PostsState, comments: CommentsState, users: UsersState}
+export type AppDispatch = typeof store.dispatch;
+// highlight-end
+```
+
+### Define Typed Compositions
+
+While it's possible to import the `RootState` and `AppDispatch` types into each component, it's **better to create typed versions of the `useDispatch` and `useSelector` compositions for usage in your application**. This is important for a couple reasons:
+
+- For `useSelector`, it saves you the need to type `(state: RootState)` every time
+- For `useDispatch`, the default `Dispatch` type does not know about thunks. In order to correctly dispatch thunks, you need to use the specific customized `AppDispatch` type from the store that includes the thunk middleware types, and use that with `useDispatch`. Adding a pre-typed `useDispatch` injectable keeps you from forgetting to import `AppDispatch` where it's needed.
+
+Since these are actual variables, not types, it's important to define them in a separate file such as `app/injectables.ts`, not the store setup file. This allows you to import them into any component file that needs to use the injectables, and avoids potential circular import dependency issues.
+
+```ts title="app/injectables.ts"
+import { useDispatch, useSelector } from "@reduxjs/vue-redux";
+import type { RootState, AppDispatch } from "./store";
+
+// highlight-start
+// Use throughout your app instead of plain `useDispatch` and `useSelector`
+export const useAppDispatch = useDispatch.withTypes<AppDispatch>();
+export const useAppSelector = useSelector.withTypes<RootState>();
+// highlight-end
+```
+
+## Application Usage
+
+### Define Slice State and Action Types
+
+Each slice file should define a type for its initial state value, so that `createSlice` can correctly infer the type of `state` in each case reducer.
+
+All generated actions should be defined using the `PayloadAction<T>` type from Redux Toolkit, which takes the type of the `action.payload` field as its generic argument.
+
+You can safely import the `RootState` type from the store file here. It's a circular import, but the TypeScript compiler can correctly handle that for types. This may be needed for use cases like writing selector functions.
+
+```ts title="features/counter/counterSlice.ts"
+import { createSlice, PayloadAction } from "@reduxjs/toolkit";
+import type { RootState } from "../../app/store";
+
+// highlight-start
+// Define a type for the slice state
+interface CounterState {
+  value: number;
+}
+
+// Define the initial state using that type
+const initialState: CounterState = {
+  value: 0,
+};
+// highlight-end
+
+export const counterSlice = createSlice({
+  name: "counter",
+  // `createSlice` will infer the state type from the `initialState` argument
+  initialState,
+  reducers: {
+    increment: (state) => {
+      state.value += 1;
+    },
+    decrement: (state) => {
+      state.value -= 1;
+    },
+    // highlight-start
+    // Use the PayloadAction type to declare the contents of `action.payload`
+    incrementByAmount: (state, action: PayloadAction<number>) => {
+      // highlight-end
+      state.value += action.payload;
+    },
+  },
+});
+
+export const { increment, decrement, incrementByAmount } = counterSlice.actions;
+
+// Other code such as selectors can use the imported `RootState` type
+export const selectCount = (state: RootState) => state.counter.value;
+
+export default counterSlice.reducer;
+```
+
+The generated action creators will be correctly typed to accept a `payload` argument based on the `PayloadAction<T>` type you provided for the reducer. For example, `incrementByAmount` requires a `number` as its argument.
+
+In some cases, [TypeScript may unnecessarily tighten the type of the initial state](https://github.com/reduxjs/redux-toolkit/pull/827). If that happens, you can work around it by casting the initial state using `as`, instead of declaring the type of the variable:
+
+```ts
+// Workaround: cast state instead of declaring variable type
+const initialState = {
+  value: 0,
+} as CounterState;
+```
+
+### Use Typed Compositions in Components
+
+In component files, import the pre-typed compositions instead of the standard injectables from Vue-Redux.
+
+```vue title="features/counter/Counter.vue"
+<script setup>
+  // highlight-next-line
+  import { useAppSelector, useAppDispatch } from "app/injectables";
+  import { decrement, increment } from "./store/counter-slice";
+
+  // highlight-start
+  // The `state` arg is correctly typed as `RootState` already
+  const count = useAppSelector((state) => state.counter.value);
+  const dispatch = useAppDispatch();
+  // highlight-end
+</script>
+
+<template>
+  <!-- omit rendering logic -->
+</template>
+```