-
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* WIP api update * WIP change of name and api * Build fix * WIP docs update * More fixes * docs(changeset): Releasing v0.1.0 * Dependency update + cleanup * docs(changeset): Rebrand to sp-hooks + more functional approach.
- Loading branch information
1 parent
f55bd4f
commit 79e7170
Showing
55 changed files
with
4,180 additions
and
3,703 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| --- | ||
| "@sp-hooks/tsconfig": minor | ||
| "@sp-hooks/prettier-config": minor | ||
| "@sp-hooks/react": minor | ||
| "@sp-hooks/eslint-config": minor | ||
| "@sp-hooks/next": minor | ||
| --- | ||
|
|
||
| Releasing v0.1.0 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| --- | ||
| "@sp-hooks/tsconfig": minor | ||
| "@sp-hooks/prettier-config": minor | ||
| "@sp-hooks/react": minor | ||
| "@sp-hooks/eslint-config": minor | ||
| "@sp-hooks/next": minor | ||
| --- | ||
|
|
||
| Rebrand to sp-hooks + more functional approach. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
22 changes: 22 additions & 0 deletions
22
apps/docs/src/content/docs/getting-started/introduction.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| --- | ||
| title: Introduction | ||
| description: Why and how to use `@sp-hooks` packages. | ||
| --- | ||
|
|
||
| ## The problem | ||
|
|
||
| With the rise of server-sided state management solutions, we find ourselves in a situation where we not only need to manage state on the client side, but also sync it with the server. | ||
|
|
||
| Here's a situation: you need to implement an e-commerce browse page, where you can filter/sort/paginate products. You store user's filters in a regular React `useState` hook, then make a client sided request to get the products. | ||
|
|
||
| Now, there's a little problem, you get a number of delays, because of all the round trips to the server. React Server Components solve this problem by removing as many of the round trips as possible, leaving you with essentially two things: API call from your frontend's backend to the API backend, and the time it takes to stream in HTML into your React application. | ||
|
|
||
| Here lies the state synchronisation problem. When prerendering the page on the server side, there's no way to access state of the `useState` hook. The best way to solve this at the moment is through the use of URL search params, which can be accessed on the server side, while each route getting its own state. | ||
|
|
||
| This means that for the route like `/products?filter=price&sort=asc&page=2`, you can get the state of the filters, sort and page, and use it to render the page on the server side. | ||
|
|
||
| ## The solution | ||
|
|
||
| In production, the code to manage the state of the URL search params becomes unmanageable quite fast. You need to parse state from the URL, update the state, and then update the URL again. This is where `@sp-hooks` come in. | ||
|
|
||
| `@sp-hooks` packages are a set of hooks that simplify management of state in a way that is both client and server side friendly. They are designed to be used with Next.js, but can be used with any React application. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,10 @@ | ||
| --- | ||
| title: Installing for Next.js applications. | ||
| description: How to install the `@sp-hooks` packages in a Next.js application. | ||
| --- | ||
|
|
||
| ## Installation | ||
|
|
||
| ```sh | ||
| npm install @sp-hooks/next | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,10 @@ | ||
| --- | ||
| title: Installing for generic React applications. | ||
| description: How to install the `@sp-hooks` packages in a generic React application. | ||
| --- | ||
|
|
||
| ## Installation | ||
|
|
||
| ```sh | ||
| npm install @sp-hooks/react | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,63 @@ | ||
| --- | ||
| title: Basic usage with Next.js. | ||
| description: The bare minimum example of sp-hooks. | ||
| --- | ||
|
|
||
| The `@sp-hooks` packages are designed to be used in conjunction with the state management solution of your choice. They are designed to be used with Next.js, but can be used with any React application. | ||
|
|
||
| ## The `useObserveAndStore` hook | ||
|
|
||
| The first thing you will want to do with `@sp-hooks` is to observe and store the state of your component. This is done with the `useObserveAndStore` hook. | ||
|
|
||
| This hook will observe the state of your component, and store it in the URL search params. This means on every change of the state, the URL will be updated to reflect the new state. | ||
|
|
||
| ```tsx | ||
| import { useObserveAndStore } from "@sp-hooks/next"; | ||
|
|
||
| const ClientComponent = () => { | ||
| const [state, setState] = useState(); | ||
|
|
||
| useObserveAndStore(state); | ||
|
|
||
| const handleClick = () => { | ||
| setState({ | ||
| hello: state.hello === "hello" ? "world" : "there" | ||
| }); | ||
| }; | ||
|
|
||
| return <button onClick={handleClick}>{state.hello}</button>; | ||
| }; | ||
| ``` | ||
|
|
||
| The `useObserveAndStore` hook expects you to pass an object with the following type: `Record<string, Value | Value[]>`, where `type Value = string | number | boolean | BigInt | Date`. | ||
|
|
||
| > Note: Since we are serializing the state to the URL, we are limited to the types that can be serialized to a string. This means that you cannot store complex objects in the URL. | ||
| ## The `searchParamsToObject` function | ||
|
|
||
| If you try the code above, you will notice that the stae is updated in React and in the URL. But if you refresh the page, the state will be lost. This is because we are not reading the state from the URL. | ||
|
|
||
| The `searchParamsToObject` function is a utility function that will convert the URL search params to an object. | ||
|
|
||
| ```tsx | ||
| import { useSearchParams } from "next/navigation"; | ||
| import { searchParamsToObject, useObserveAndStore } from "@sp-hooks/next"; | ||
|
|
||
| const ClientComponent = () => { | ||
| const searchParams = useSearchParams(); | ||
|
|
||
| const [state, setState] = useState(searchParamsToObject(searchParams)); | ||
|
|
||
| useObserveAndStore(state); | ||
|
|
||
| const handleClick = () => { | ||
| setState({ | ||
| hello: state.hello === "hello" ? "world" : "there" | ||
| }); | ||
| }; | ||
|
|
||
| return <button onClick={handleClick}>{state.hello}</button>; | ||
| }; | ||
| ``` | ||
|
|
||
| Now when you refresh the page, the state will be read from the URL and passed as initial state of `useState` hook. The button will reflect the state. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,47 @@ | ||
| --- | ||
| title: Default Values | ||
| description: How to set default values for your state. | ||
| --- | ||
|
|
||
| When using default values you have to do a couple of things: | ||
|
|
||
| - Provide default values to your state manager. | ||
| - Provide the same default values to `useObserveAndStore` hook, if you want to remove default values from search params when they are set to the default value. | ||
|
|
||
| ## Example | ||
|
|
||
| ```tsx | ||
| import { useObserveAndStore } from "@sp-hooks/next"; | ||
|
|
||
| const ClientComponent = () => { | ||
| const [state, setState] = useState({ | ||
| greeting: "hello", | ||
| }); | ||
|
|
||
| useObserveAndStore(state, { | ||
| defaultValues: { | ||
| greeting: "hello", | ||
| }, | ||
| }); | ||
|
|
||
| return <button>{state.greeting}</button>; | ||
| } | ||
| ``` | ||
|
|
||
| ## A cleaner version | ||
|
|
||
| ```tsx | ||
| import { useObserveAndStore } from "@sp-hooks/next"; | ||
|
|
||
| const defaultValues = { | ||
| greeting: "hello", | ||
| }; | ||
|
|
||
| const ClientComponent = () => { | ||
| const [state, setState] = useState(defaultValues); | ||
|
|
||
| useObserveAndStore(state, { defaultValues }); | ||
|
|
||
| return <button>{state.greeting}</button>; | ||
| } | ||
| ``` |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,29 @@ | ||
| --- | ||
| title: Basic usage with Jotai and Next.js | ||
| description: The bare minimum example of using sp-hooks with Jotai and Next.js. | ||
| --- | ||
|
|
||
| ## Example | ||
|
|
||
| ```tsx | ||
| import { useObserveAndStore } from "@sp-hooks/next"; | ||
| import { atom, useAtom } from "jotai"; | ||
|
|
||
| const stateAtom = atom({ | ||
| hello: "hello" | ||
| }); | ||
|
|
||
| const ClientComponent = () => { | ||
| const [state, setState] = useAtom(stateAtom); | ||
|
|
||
| useObserveAndStore(state); | ||
|
|
||
| const handleClick = () => { | ||
| setState({ | ||
| hello: state.hello === "hello" ? "world" : "there" | ||
| }); | ||
| }; | ||
|
|
||
| return <button onClick={handleClick}>{state.hello}</button>; | ||
| }; | ||
| ``` |
Oops, something went wrong.