diff --git a/docs/introduction/getting-started.md b/docs/introduction/getting-started.md new file mode 100644 index 0000000..b6cb8dd --- /dev/null +++ b/docs/introduction/getting-started.md @@ -0,0 +1,114 @@ +--- +id: getting-started +title: Getting Started with Angular Redux +hide_title: true +sidebar_label: Getting Started +description: 'Introduction > Getting Started: First steps with Angular Redux' +--- + +# Getting Started with Angular Redux + +[Angular Redux](https://github.com/reduxjs/angular-redux) is the official [Angular](https://angular.dev/) UI bindings layer for [Redux](https://redux.js.org/). It lets your Angular components read data from a Redux store, and dispatch actions to the store to update state. + +## Installation + +Angular Redux 8.x requires **Angular 17.3 or later**, in order to make use of Angular Signals. + +### Installing with `ng add` + +You can install the Store to your project with the following `ng add` command (details here): + +```sh +ng add @reduxjs/angular-redux@latest +``` + +#### Optional `ng add` flags + +| flag | description | value type | default value | +|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|---------------| +| `--path` | Path to the module that you wish to add the import for the `provideRedux` to. | `string` || +| `--project` | Name of the project defined in your `angular.json` to help locating the module to add the `provideRedux` to. | `string` || +| `--module` | Name of file containing the module that you wish to add the import for the `provideRedux` to. Can also include the relative path to the file. For example, `src/app/app.module.ts`. | `string` | `app` | +| `--storePath` | The file path to create the state in. | `string` | `store` | + +This command will automate the following steps: + +1. Update `package.json` > `dependencies` with Redux, Redux Toolkit, and Angular Redux +2. Run `npm install` to install those dependencies. +3. Update your `src/app/app.module.ts` > `imports` array with `provideRedux({store})` +4. If the project is using a `standalone bootstrap`, it adds `provideRedux({store})` into the application config. + +### Installing with `npm` or `yarn` + +To use Angular Redux with your Angular app, install it as a dependency: + +```bash +# If you use npm: +npm install @reduxjs/angular-redux + +# Or if you use Yarn: +yarn add @reduxjs/angular-redux +``` + + +You'll also need to [install Redux](https://redux.js.org/introduction/installation) and [set up a Redux store](https://redux.js.org/recipes/configuring-your-store/) in your app. + +Angular-Redux is written in TypeScript, so all types are automatically included. + +## API Overview + +### `provideRedux` + +Angular Redux includes a `provideRedux` provider factory, which makes the Redux store available to the rest of your app: + +```typescript +import { bootstrapApplication } from '@angular/platform-browser'; +import { provideRedux } from "angular-redux"; +import { AppComponent } from './app/app.component'; +import { store } from './store' + +bootstrapApplication(AppComponent, { + providers: [ + provideRedux({ store }) + ] +}); +``` + +### Injectables + +Angular Redux provides a pair of custom Angular injectable functions that allow your Angular components to interact with the Redux store. + +`injectSelector` reads a value from the store state and subscribes to updates, while `injectDispatch` returns the store's `dispatch` method to let you dispatch actions. + +```typescript +import { Component } from '@angular/core' +import { injectSelector, injectDispatch } from "@reduxjs/angular-redux"; +import { decrement, increment } from './store/counter-slice' +import { RootState } from './store' + +@Component({ + selector: 'app-root', + standalone: true, + template: ` + + {{ count() }} + + ` +}) +export class AppComponent { + count = injectSelector((state: RootState) => state.counter.value) + dispatch = injectDispatch() + increment = increment + decrement = decrement +} +``` + +## Help and Discussion + +The **[#redux channel](https://discord.gg/0ZcbPKXt5bZ6au5t)** of the **[Reactiflux Discord community](http://www.reactiflux.com)** is our official resource for all questions related to learning and using Redux. Reactiflux is a great place to hang out, ask questions, and learn - come join us! + +You can also ask questions on [Stack Overflow](https://stackoverflow.com) using the **[#redux tag](https://stackoverflow.com/questions/tagged/redux)**. diff --git a/docs/tutorials/quick-start.md b/docs/tutorials/quick-start.md new file mode 100644 index 0000000..34b1429 --- /dev/null +++ b/docs/tutorials/quick-start.md @@ -0,0 +1,211 @@ +--- +id: quick-start +title: Quick Start +sidebar_label: Quick Start +hide_title: true +--- + +  + +# Angular Redux Quick Start + +:::tip What You'll Learn + +- How to set up and use Redux Toolkit with Angular Redux + +::: + +:::info Prerequisites + +- Familiarity with [ES6 syntax and features](https://www.taniarascia.com/es6-syntax-and-feature-overview/) +- Knowledge of Angular terminology: [State](https://angular.dev/essentials/managing-dynamic-data), [Components, Props](https://angular.dev/essentials/components), and [Signals](https://angular.dev/guide/signals) +- Understanding of [Redux terms and concepts](https://redux.js.org/tutorials/fundamentals/part-2-concepts-data-flow) + +::: + +## Introduction + +Welcome to the Angular Redux Quick Start tutorial! **This tutorial will briefly introduce you to Angular Redux and teach you how to start using it correctly**. + +### How to Read This Tutorial + +This page will focus on just how to set up a Redux application with Redux Toolkit and the main APIs you'll use. For explanations of what Redux is, how it works, and full examples of how to use Redux Toolkit, see [the Redux core docs tutorials](https://redux.js.org/tutorials/index). + +For this tutorial, we assume that you're using Redux Toolkit and Angular Redux together, as that is the standard Redux usage pattern. The examples are based on [a typical Angular CLI folder structure](https://angular.dev/tools/cli) where all the application code is in a `src`, but the patterns can be adapted to whatever project or folder setup you're using. + +## Usage Summary + +### Install Redux Toolkit and Angular Redux + +Add the Redux Toolkit and Angular Redux packages to your project: + +```sh +npm install @reduxjs/toolkit angular-redux +``` + +### Create a Redux Store + +Create a file named `src/app/store.js`. Import the `configureStore` API from Redux Toolkit. We'll start by creating an empty Redux store, and exporting it: + +```typescript title="app/store.js" +import { configureStore } from '@reduxjs/toolkit' + +export default configureStore({ + reducer: {}, +}) +``` + +This creates a Redux store, and also automatically configure the Redux DevTools extension so that you can inspect the store while developing. + +### Provide the Redux Store to Angular + +Once the store is created, we can make it available to our Angular components by putting an Angular Redux `provideRedux` in our application's `providers` array in `src/main.ts`. Import the Redux store we just created, put a `provideRedux` in your application's `providers` array, and pass the store as a prop: + +```typescript title="main.ts" + +import { bootstrapApplication } from '@angular/platform-browser'; +import { AppComponent } from './app/app.component'; +// highlight-start +import { provideRedux } from "angular-redux"; +import { store } from './store' +// highlight-end + +bootstrapApplication(AppComponent, { + providers: [ + // highlight-next-line + provideRedux({ store }) + ] +}); +``` + +### Create a Redux State Slice + +Add a new file named `src/features/counter/counterSlice.js`. In that file, import the `createSlice` API from Redux Toolkit. + +Creating a slice requires a string name to identify the slice, an initial state value, and one or more reducer functions to define how the state can be updated. Once a slice is created, we can export the generated Redux action creators and the reducer function for the whole slice. + +Redux requires that [we write all state updates immutably, by making copies of data and updating the copies](https://redux.js.org/tutorials/fundamentals/part-2-concepts-data-flow#immutability). However, Redux Toolkit's `createSlice` and `createReducer` APIs use [Immer](https://immerjs.github.io/immer/) inside to allow us to [write "mutating" update logic that becomes correct immutable updates](https://redux.js.org/tutorials/fundamentals/part-8-modern-redux#immutable-updates-with-immer). + +```js title="features/counter/counterSlice.js" +import { createSlice } from '@reduxjs/toolkit' + +export const counterSlice = createSlice({ + name: 'counter', + initialState: { + value: 0, + }, + reducers: { + increment: (state) => { + // Redux Toolkit allows us to write "mutating" logic in reducers. It + // doesn't actually mutate the state because it uses the Immer library, + // which detects changes to a "draft state" and produces a brand new + // immutable state based off those changes. + // Also, no return statement is required from these functions. + state.value += 1 + }, + decrement: (state) => { + state.value -= 1 + }, + incrementByAmount: (state, action) => { + state.value += action.payload + }, + }, +}) + +// Action creators are generated for each case reducer function +export const { increment, decrement, incrementByAmount } = counterSlice.actions + +export default counterSlice.reducer +``` + +### Add Slice Reducers to the Store + +Next, we need to import the reducer function from the counter slice and add it to our store. By defining a field inside the `reducer` parameter, we tell the store to use this slice reducer function to handle all updates to that state. + +```js title="app/store.js" +import { configureStore } from '@reduxjs/toolkit' +// highlight-next-line +import counterReducer from '../features/counter/counterSlice' + +export default configureStore({ + reducer: { + // highlight-next-line + counter: counterReducer, + }, +}) +``` + +### Use Redux State and Actions in Angular Components + +Now we can use the Angular Redux inject functions to let Angular components interact with the Redux store. We can read data from the store with `useSelector`, and dispatch actions using `useDispatch`. Create a `src/features/counter/counter.component.ts` file with a `` component inside, then import that component into `app.component.ts` and render it inside of ``. + +```typescript title="features/counter/counter.component.ts" +import { Component } from '@angular/core' +import { injectSelector, injectDispatch } from "@reduxjs/angular-redux"; +import { decrement, increment } from './store/counter-slice' +import { RootState } from './store' + +@Component({ + selector: 'app-counter', + standalone: true, + template: ` + + {{ count() }} + + ` +}) +export class CounterComponent { + count = injectSelector((state: RootState) => state.counter.value) + dispatch = injectDispatch() + increment = increment + decrement = decrement +} +``` + +Now, any time you click the "Increment" and "Decrement buttons: + +- The corresponding Redux action will be dispatched to the store +- The counter slice reducer will see the actions and update its state +- The `` component will see the new state value from the store and re-render itself with the new data + +## What You've Learned + +That was a brief overview of how to set up and use Redux Toolkit with Angular. Recapping the details: + +:::tip Summary + +- **Create a Redux store with `configureStore`** + - `configureStore` accepts a `reducer` function as a named argument + - `configureStore` automatically sets up the store with good default settings +- **Provide the Redux store to the Angular application components** + - Put a Angular Redux `provideRedux` provider factory in your `bootstrapApplication`'s `providers` array + - Pass the Redux store as `` +- **Create a Redux "slice" reducer with `createSlice`** + - Call `createSlice` with a string name, an initial state, and named reducer functions + - Reducer functions may "mutate" the state using Immer + - Export the generated slice reducer and action creators +- **Use the Angular Redux `injectSelector/injectDispatch` injections in Angular components** + - Read data from the store with the `injectSelector` injection + - Get the `dispatch` function with the `injectDispatch` injection, and dispatch actions as needed + +::: + +### Full Counter App Example + +Here's the complete Counter application as a running CodeSandbox: + + + +## What's Next? + +We recommend going through [**the "Redux Essentials" and "Redux Fundamentals" tutorials in the Redux core docs**](https://redux.js.org/tutorials/index), which will give you a complete understanding of how Redux works, what Redux Toolkit and Angular Redux do, and how to use it correctly. diff --git a/docs/tutorials/typescript.md b/docs/tutorials/typescript.md new file mode 100644 index 0000000..37df09a --- /dev/null +++ b/docs/tutorials/typescript.md @@ -0,0 +1,171 @@ +--- +id: typescript-quick-start +title: TypeScript Quick Start +sidebar_label: TypeScript Quick Start +hide_title: true +--- + +  + +# Angular Redux TypeScript Quick Start + +:::tip What You'll Learn + +- How to set up and use Redux Toolkit and Angular Redux with TypeScript + +::: + +:::info Prerequisites + +- Knowledge of Angular [Signals](https://angular.dev/guide/signals) +- 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 Angular Redux TypeScript Quick Start tutorial! **This tutorial will briefly show how to use TypeScript with Redux Toolkit and Angular-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). + +[Angular 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 +// Inferred type: {posts: PostsState, comments: CommentsState, users: UsersState} +export type AppDispatch = typeof store.dispatch +// highlight-end +``` + +### Define Typed Injectables + +While it's possible to import the `RootState` and `AppDispatch` types into each component, it's **better to create typed versions of the `injectDispatch` and `injectSelector` injectables for usage in your application**. This is important for a couple reasons: + +- For `injectSelector`, it saves you the need to type `(state: RootState)` every time +- For `injectDispatch`, 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 `injectDispatch`. Adding a pre-typed `injectDispatch` 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 { injectDispatch, injectSelector } from '@reduxjs/angular-redux' +import type { RootState, AppDispatch } from './store' + +// highlight-start +// Use throughout your app instead of plain `injectDispatch` and `injectSelector` +export const injectAppDispatch = injectDispatch.withTypes() +export const injectAppSelector = injectSelector.withTypes() +// 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` 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) => { + // 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` 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 Injectables in Components + +In component files, import the pre-typed injectables instead of the standard injectables from Angular-Redux. + +```typescript title="features/counter/counter.component.ts" +import { Component } from '@angular/core' +// highlight-next-line +import { injectAppSelector, injectAppDispatch } from "app/injectables"; +import { decrement, increment } from './store/counter-slice' + +@Component({ + selector: 'app-counter', + standalone: true, + // omit rendering logic +}) +export class CounterComponent { + // highlight-start + // The `state` arg is correctly typed as `RootState` already + count = injectAppSelector(state => state.counter.value) + dispatch = injectAppDispatch() + // highlight-end + increment = increment + decrement = decrement +} +``` diff --git a/package.json b/package.json index 580816e..c52b8d3 100644 --- a/package.json +++ b/package.json @@ -4,9 +4,11 @@ "scripts": { "ng": "ng", "start": "ng serve", + "start:docs": "yarn workspace website run start", "build": "ng build angular-redux && tsc -p projects/angular-redux/tsconfig.schematics.json && yarn build:copy", "build:copy": "cd ./projects/angular-redux/schematics && copyfiles \"**/*.json\" ../../../dist/angular-redux/schematics && copyfiles \"**/*.template\" ../../../dist/angular-redux/schematics", "build:ng": "ng build", + "build:docs": "yarn workspace website run build", "watch": "ng build --watch --configuration development", "test": "yarn test:ng && yarn test:schematics", "test:ng": "ng test", @@ -14,7 +16,8 @@ }, "workspaces": { "packages": [ - "projects/*" + "projects/*", + "website" ] }, "private": true, diff --git a/website/.gitignore b/website/.gitignore new file mode 100644 index 0000000..9a0a739 --- /dev/null +++ b/website/.gitignore @@ -0,0 +1,22 @@ +# dependencies +/node_modules +/package.lock.json + +# production +/build + +# generated files +.docusaurus/ +website/.docusaurus/ +.cache-loader + +# misc +.DS_Store +.env.local +.env.development.local +.env.test.local +.env.production.local + +npm-debug.log* +yarn-debug.log* +yarn-error.log* diff --git a/website/README.md b/website/README.md new file mode 100644 index 0000000..0566861 --- /dev/null +++ b/website/README.md @@ -0,0 +1,198 @@ +This website was created with [Docusaurus](https://docusaurus.io/). + +# What's In This Document + +- [Get Started in 5 Minutes](#get-started-in-5-minutes) +- [Directory Structure](#directory-structure) +- [Editing Content](#editing-content) +- [Adding Content](#adding-content) +- [Full Documentation](#full-documentation) + +# Get Started in 5 Minutes + +1. Make sure all the dependencies for the website are installed: + +```sh +# Install dependencies +$ yarn +``` + +2. Run your dev server: + +```sh +# Start the site +$ yarn start +``` + +## Directory Structure + +Your project file structure should look something like this + +``` +my-docusaurus/ + docs/ + doc-1.md + doc-2.md + doc-3.md + website/ + blog/ + 2016-3-11-oldest-post.md + 2017-10-24-newest-post.md + core/ + node_modules/ + pages/ + static/ + css/ + img/ + package.json + sidebar.json + siteConfig.js +``` + +# Editing Content + +## Editing an existing docs page + +Edit docs by navigating to `docs/` and editing the corresponding document: + +`docs/doc-to-be-edited.md` + +```markdown +--- +id: page-needs-edit +title: This Doc Needs To Be Edited +--- + +Edit me... +``` + +For more information about docs, click [here](https://docusaurus.io/docs/en/navigation) + +## Editing an existing blog post + +Edit blog posts by navigating to `website/blog` and editing the corresponding post: + +`website/blog/post-to-be-edited.md` + +```markdown +--- +id: post-needs-edit +title: This Blog Post Needs To Be Edited +--- + +Edit me... +``` + +For more information about blog posts, click [here](https://docusaurus.io/docs/en/adding-blog) + +# Adding Content + +## Adding a new docs page to an existing sidebar + +1. Create the doc as a new markdown file in `/docs`, example `docs/newly-created-doc.md`: + +```md +--- +id: newly-created-doc +title: This Doc Needs To Be Edited +--- + +My new content here.. +``` + +1. Refer to that doc's ID in an existing sidebar in `website/sidebar.json`: + +```javascript +// Add newly-created-doc to the Getting Started category of docs +{ + "docs": { + "Getting Started": [ + "quick-start", + "newly-created-doc" // new doc here + ], + ... + }, + ... +} +``` + +For more information about adding new docs, click [here](https://docusaurus.io/docs/en/navigation) + +## Adding a new blog post + +1. Make sure there is a header link to your blog in `website/siteConfig.js`: + +`website/siteConfig.js` + +```javascript +headerLinks: [ + ... + { blog: true, label: 'Blog' }, + ... +] +``` + +2. Create the blog post with the format `YYYY-MM-DD-My-Blog-Post-Title.md` in `website/blog`: + +`website/blog/2018-05-21-New-Blog-Post.md` + +```markdown +--- +author: Frank Li +authorURL: https://twitter.com/foobarbaz +authorFBID: 503283835 +title: New Blog Post +--- + +Lorem Ipsum... +``` + +For more information about blog posts, click [here](https://docusaurus.io/docs/en/adding-blog) + +## Adding items to your site's top navigation bar + +1. Add links to docs, custom pages or external links by editing the headerLinks field of `website/siteConfig.js`: + +`website/siteConfig.js` + +```javascript +{ + headerLinks: [ + ... + /* you can add docs */ + { doc: 'my-examples', label: 'Examples' }, + /* you can add custom pages */ + { page: 'help', label: 'Help' }, + /* you can add external links */ + { href: 'https://github.com/facebook/Docusaurus', label: 'GitHub' }, + ... + ], + ... +} +``` + +For more information about the navigation bar, click [here](https://docusaurus.io/docs/en/navigation) + +## Adding custom pages + +1. Docusaurus uses React components to build pages. The components are saved as .js files in `website/pages/en`: +1. If you want your page to show up in your navigation header, you will need to update `website/siteConfig.js` to add to the `headerLinks` element: + +`website/siteConfig.js` + +```javascript +{ + headerLinks: [ + ... + { page: 'my-new-custom-page', label: 'My New Custom Page' }, + ... + ], + ... +} +``` + +For more information about custom pages, click [here](https://docusaurus.io/docs/en/custom-pages). + +# Full Documentation + +Full documentation can be found on the [website](https://docusaurus.io/). diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js new file mode 100644 index 0000000..af8d56f --- /dev/null +++ b/website/docusaurus.config.js @@ -0,0 +1,173 @@ +/** + * Copyright (c) 2017-present, Facebook, Inc. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +// See https://docusaurus.io/docs/site-config for all the possible +// site configuration options. + +const siteConfig = { + presets: [ + [ + '@docusaurus/preset-classic', + { + docs: { + path: '../docs', + routeBasePath: '/', + sidebarPath: require.resolve('./sidebars.js'), + showLastUpdateTime: true, + editUrl: 'https://github.com/reduxjs/angular-redux/edit/main/website', + include: [ + '{introduction,tutorials}/*.{md,mdx}' + ], // no other way to exclude node_modules + }, + theme: { + customCss: [ + require.resolve('./static/css/custom.css'), + require.resolve('./static/css/404.css'), + require.resolve('./static/css/codeblock.css'), + ], + }, + }, + ], + ], + title: 'Angular Redux', // Title for your website. + onBrokenLinks: 'throw', + tagline: 'Official Angular bindings for Redux', + url: 'https://angular-redux.js.org', // Your website URL + baseUrl: '/', + // Used for publishing and more + projectName: 'angular-redux', + organizationName: 'reduxjs', + + // For no header links in the top nav bar -> headerLinks: [], + /* path to images for header/footer */ + favicon: 'img/favicon/favicon.ico', + + // Add custom scripts here that would be placed in