docs: state management

Author: stephancill

.changeset/curly-badgers-drum.md

@@ -0,0 +1,5 @@
+---
+"docs": patch
+---
+
+docs: state management

.changeset/fast-wasps-yawn.md

@@ -0,0 +1,5 @@
+---
+"framesjs-starter": patch
+---
+
+fix: state management generic type demo

docs/pages/guides/state-management.mdx

@@ -0,0 +1,72 @@
+---
+title: "Guide: Frames.js State"
+description: "Frames.js is the react based framework for making frames. Debugger included."
+---
+
+# Guide: State Management in Frames.js
+
+State in Frames.js is a way for you to store data that you want to use in between frames requests. The frames spec allows up to 4kb of data to be stored in the state object.
+
+## Setup
+
+To use state in frames.js, you should declare the initial state in your `createFrames` call. If your state type is not declared explicitly it will be derived from the initial state.
+
+```ts [frames.ts]
+import { createFrames } from "@framesjs/next";
+
+export type State = {
+  count: number;
+};
+
+export const frames = createFrames<State>({
+  initialState: {
+    count: 0,
+  },
+});
+```
+
+## Accessing state
+
+You can access the state object in your frame on the `ctx` parameter. The initial frame will have the state object with the initial values.
+
+```ts [route.tsx]
+import { frames } from "./frames";
+
+const handler = frames(async ({ ctx }) => {
+  return {
+    image: <div tw="flex">Count: {ctx.state.count}</div>, // [!code focus]
+  };
+});
+
+export const GET = handler;
+export const POST = handler;
+```
+
+## Updating state
+
+To update the state, you just include the updated state object in your handler's [`FrameDefinition`](/reference/core/createFrames#framedefinition) return value.
+
+```ts [route.tsx]
+import { frames, Button } from "./frames";
+
+const handler = frames(async ({ ctx }) => {
+  const currentState = ctx.state;
+
+  // Update the state // [!code focus]
+  const updatedState = { // [!code focus]
+    ...currentState, // [!code focus]
+    count: currentState.count + 1, // [!code focus]
+  }; // [!code focus]
+
+  return {
+    image: <div tw="flex">Count: {updatedState.count}`</div>, // [!code focus],
+    buttons: [
+      <Button action="post">Increment</Button>
+    ],
+    state: updatedState, // [!code focus]
+  };
+});
+
+export const GET = handler;
+export const POST = handler;
+```

docs/vocs.config.tsx

@@ -22,6 +22,10 @@ const sidebar = [
         text: "Multi-page Frames",
         link: "/guides/multiple-frames",
       },
+      {
+        text: "State Management",
+        link: "/guides/state-management",
+      },
       {
         text: "Deploying your Frame",
         link: "/guides/deployment",
@@ -87,9 +91,9 @@ const sidebar = [
         link: "/reference/core/remix",
       },
       {
-        text: 'Cloudflare Workers',
-        link: '/reference/core/cloudflare-workers'
-      }
+        text: "Cloudflare Workers",
+        link: "/reference/core/cloudflare-workers",
+      },
     ],
   },
   {

examples/framesjs-starter/app/frames/frames.ts

@@ -1,6 +1,10 @@
 import { createFrames } from "frames.js/next";
 
-export const frames = createFrames({
+type State = {
+  counter: number;
+};
+
+export const frames = createFrames<State>({
   basePath: "/frames",
   initialState: { counter: 0 },
 });