docs: document createVars & driver-specific values (#787)

Author: NathanFlurry

docs/concepts/lifecycle.mdx

@@ -13,6 +13,51 @@ Actor lifecycle hooks are defined as functions in the actor configuration.
 
 The `createState` function or `state` constant defines the initial state of the actor (see [state documentation](/concepts/state)). The `createState` function is called only once when the actor is first created.
 
+### `createVars` and `vars`
+
+The `createVars` function or `vars` constant defines ephemeral variables for the actor (see [state documentation](/concepts/state)). These variables are not persisted and are useful for storing runtime-only objects or temporary data.
+
+The `createVars` function can also receive driver-specific context as its second parameter, allowing access to driver capabilities like Rivet KV or Cloudflare Durable Object storage.
+
+```typescript
+import { actor } from "actor-core";
+
+// Using vars constant
+const counter1 = actor({
+  state: { count: 0 },
+  vars: { lastAccessTime: 0 },
+  actions: { /* ... */ }
+});
+
+// Using createVars function
+const counter2 = actor({
+  state: { count: 0 },
+  createVars: () => {
+    // Initialize with non-serializable objects
+    return { 
+      lastAccessTime: Date.now(),
+      emitter: createNanoEvents() 
+    };
+  },
+  actions: { /* ... */ }
+});
+
+// Access driver-specific context
+const exampleActor = actor({
+  state: { count: 0 },
+  // Access driver context in createVars
+  createVars: (c, rivet) => ({
+    ctx: rivet.ctx,
+  }),
+  actions: {
+    doSomething: (c) => {
+      // Use driver-specific context
+      console.log(`Region: ${c.vars.rivet.metadata.region.name}`);
+    }
+  }
+});
+```
+
 ### `onCreate`
 
 The `onCreate` hook is called at the same time as `createState`, but unlike `createState`, it doesn't return any value. Use this hook for initialization logic that doesn't affect the initial state.

docs/drivers/overview.mdx

@@ -9,6 +9,10 @@ Drivers in ActorCore the infrastructure layer between your actor code and the un
 
 <DriverNote />
 
+## Accessing Driver Context
+
+Drivers expose a custom driver context for functionality specific to the given driver. This can be accessed as a parameter to `createVars` then later accessed with `c.vars`. Read more about the [`createVars` lifecycle hook](/concepts/lifecycle).
+
 ## Available Drivers
 
 Choose a driver based on your deployment needs - [Memory](/drivers/memory) for development, [Rivet](/drivers/rivet) or [Cloudflare Workers](/drivers/cloudflare-workers) for production environments, and [Redis](/drivers/redis) for specialized self-hosted scenarios.

docs/platforms/cloudflare-workers.mdx

@@ -189,6 +189,31 @@ If you already have a Cloudflare Workers project and want to add ActorCore, you
 	</Step>
 </Steps>
 
+## Accessing Cloudflare Context And Bindings
+
+[Cloudflare-specific `DurableObjectState`](https://developers.cloudflare.com/durable-objects/api/state/) and environment bindings can be accessed from `createVars`.
+
+```typescript
+import { actor } from "actor-core";
+
+const myActor = actor({
+  // Load Cloudflare-specific variables
+  createVars: (c, cloudflare) => ({
+	ctx: cloudflare.ctx,
+	env: cloudflare.env,
+  }),
+  actions: {
+	foo: async (c) => {
+	  // Access DurableObjectState
+	  await c.vars.ctx.storage.get("foo");
+
+	  // Access bindings
+	  await c.vars.env.MY_BUCKET.put(key, "foo");
+	},
+  }
+});
+```
+
 ## Available Regions
 
 See available regions [here](https://developers.cloudflare.com/durable-objects/reference/data-location/#supported-locations-1).

docs/platforms/rivet.mdx

@@ -92,6 +92,28 @@ import CreateActorCli from '/snippets/create-actor-cli.mdx';
 	</Step>
 </Steps>
 
+## Accessing Rivet Context
+
+[Rivet's `ActorContext`](https://rivet.gg/docs/javascript-runtime#the-actor-context-object) can be accessed from `createVars`.
+
+```typescript
+import { actor } from "actor-core";
+
+const myActor = actor({
+  // Load Rivet-specific variables
+  createVars: (c, rivet) => ({
+	rivet: rivet.ctx,
+  }),
+  actions: {
+	foo: async (c) => {
+	  // Access ActorContext
+	  c.log.info(`Region: ${c.vars.rivet.metadata.region.name}`);
+	  await c.vars.rivet.kv.get("foo");
+	},
+  }
+});
+```
+
 ## Available Regions
 
 Rivet supports deploying your actors to multiple regions automatically. You can specify region preferences in your Rivet project settings in the Rivet Hub.