alchemy 0.68.0 → 0.69.1

package/src/docker/container.ts

@@ -59,6 +59,62 @@ export interface NetworkMapping {
   aliases?: string[];
 }
 
+/**
+ * Duration value supporting both number (seconds) and string format (value + unit)
+ * Units: ms (milliseconds), s (seconds), m (minutes), h (hours)
+ * Examples: 30, "30s", "1m", "500ms", "2h"
+ */
+export type Duration = number | `${number}${"ms" | "s" | "m" | "h"}`;
+
+/**
+ * Healthcheck configuration
+ */
+export interface HealthcheckConfig {
+  /**
+   * Command to run to check health.
+   * Can be an array of command arguments or a shell command string.
+   * Examples:
+   * - ["curl", "-f", "http://localhost/"]
+   * - "curl -f http://localhost/ || exit 1"
+   */
+  cmd: string[] | string;
+
+  /**
+   * Time between running the check
+   * Can be a number (in seconds) or string with unit (e.g., "30s", "1m")
+   * @default 0
+   */
+  interval?: Duration;
+
+  /**
+   * Maximum time to allow one check to run
+   * Can be a number (in seconds) or string with unit (e.g., "10s", "500ms")
+   * @default 0
+   */
+  timeout?: Duration;
+
+  /**
+   * Consecutive failures needed to report unhealthy
+   */
+  retries?: number;
+
+  /**
+   * Start period for the container to initialize before starting
+   * health-retries countdown
+   * Can be a number (in seconds) or string with unit (e.g., "40s", "1m")
+   * @default 0
+   */
+  startPeriod?: Duration;
+
+  /**
+   * Time between running the check during the start period
+   * Can be a number (in seconds) or string with unit (e.g., "5s", "500ms")
+   * Requires Docker API 1.44+
+   * @default 0
+   */
+  startInterval?: Duration;
+}
+
 /**
  * Properties for creating a Docker container
  */
@@ -115,6 +171,11 @@ export interface ContainerProps {
    * Start the container after creation
    */
   start?: boolean;
+
+  /**
+   * Healthcheck configuration
+   */
+  healthcheck?: HealthcheckConfig;
 }
 
 /**
@@ -172,6 +233,41 @@ export interface Container extends ContainerProps {
  *   restart: "always",
  *   start: true
  * });
+ *
+ * @example
+ * // Create a container with healthcheck using numeric values (seconds)
+ * const healthyContainer = await Container("api", {
+ *   image: "my-api:latest",
+ *   ports: [
+ *     { external: 3000, internal: 3000 }
+ *   ],
+ *   healthcheck: {
+ *     cmd: ["curl", "-f", "http://localhost:3000/health"],
+ *     interval: 30,
+ *     timeout: 10,
+ *     retries: 3,
+ *     startPeriod: 40
+ *   },
+ *   start: true
+ * });
+ *
+ * @example
+ * // Create a container with healthcheck using string duration format
+ * const healthyContainer2 = await Container("api2", {
+ *   image: "my-api:latest",
+ *   ports: [
+ *     { external: 3001, internal: 3000 }
+ *   ],
+ *   healthcheck: {
+ *     cmd: ["curl", "-f", "http://localhost:3000/health"],
+ *     interval: "30s",
+ *     timeout: "10s",
+ *     retries: 3,
+ *     startPeriod: "1m",
+ *     startInterval: "500ms"
+ *   },
+ *   start: true
+ * });
  */
 export const Container = Resource(
   "docker::Container",
@@ -245,6 +341,7 @@ export const Container = Resource(
         env: props.environment,
         volumes: volumeMappings,
         cmd: props.command,
+        healthcheck: props.healthcheck,
       });
 
       // Connect to networks if specified

package/src/llms.cloudflare.txt

@@ -301,7 +301,7 @@ const app = await alchemy("my-app", {
 ### Framework Integration (Vite/React/etc.)
 ```typescript
 const website = await Vite("website", {
-  main: "./src/worker.ts",
+  entrypoint: "./src/worker.ts",
   command: "bun run build", // Build command
   bindings: {
     API: await Worker("api", { entrypoint: "./api/worker.ts" }),
@@ -319,7 +319,7 @@ await alchemy.run("backend", async () => {
 });
 
 await alchemy.run("frontend", async () => {
-  await Vite("website", { main: "./src/worker.ts" });
+  await Vite("website", { entrypoint: "./src/worker.ts" });
 });
 ```
 

package/src/neon/branch.ts

@@ -76,7 +76,7 @@ export interface NeonBranchProps extends NeonApiOptions {
   endpoints: neon.BranchCreateRequestEndpointOptions[];
 }
 
-export interface NeonBranch extends Resource<"neon::Branch"> {
+export interface NeonBranch {
   /**
    * The branch ID. This value is generated when a branch is created. A branch_id value has a br- prefix. For example: br-small-term-683261.
    */
@@ -215,7 +215,7 @@ export const NeonBranch = Resource(
           ),
         );
 
-        return this({
+        return {
           id: data.branch.id,
           name: data.branch.name,
           projectId: data.branch.project_id,
@@ -237,7 +237,7 @@ export const NeonBranch = Resource(
           databases: data.databases,
           roles: data.roles.map(formatRole),
           connectionUris: data.connection_uris?.map(formatConnectionUri) ?? [],
-        });
+        };
       }
       case "update": {
         if (
@@ -263,7 +263,8 @@ export const NeonBranch = Resource(
             },
           },
         });
-        return this({
+
+        return {
           ...this.output,
           name,
           protected: data.branch.protected,
@@ -271,7 +272,7 @@ export const NeonBranch = Resource(
           expiresAt: data.branch.expires_at
             ? new Date(data.branch.expires_at)
             : undefined,
-        });
+        };
       }
     }
   },

package/src/neon/project.ts

@@ -229,7 +229,7 @@ export const NeonProject = Resource(
             .then((res) => res.data.endpoints),
         ]);
 
-        return this({
+        return {
           id: data.project.id,
           name: data.project.name,
           created_at: data.project.created_at,
@@ -248,7 +248,7 @@ export const NeonProject = Resource(
           databases: data.databases as [neon.Database, ...neon.Database[]],
           branch,
           endpoints: endpoints as [neon.Endpoint, ...neon.Endpoint[]],
-        });
+        };
       }
       case "update": {
         const { data } = await api.updateProject({
@@ -264,7 +264,7 @@ export const NeonProject = Resource(
             },
           },
         });
-        return this({
+        return {
           ...this.output,
           name: data.project.name,
           updated_at: data.project.updated_at,
@@ -274,7 +274,7 @@ export const NeonProject = Resource(
           settings: data.project.settings,
           default_endpoint_settings: data.project.default_endpoint_settings,
           history_retention_seconds: data.project.history_retention_seconds,
-        });
+        };
       }
       case "delete": {
         if (this.output?.id) {

package/src/serde.ts

@@ -119,6 +119,10 @@ export async function serialize(
         .filter((prop) => prop === "env")
         .map((prop) => [prop, (value as any)[prop]]),
     );
+  } else if (isBinary(value)) {
+    return {
+      "@buffer": await serializeBinary(value),
+    };
   } else if (value && typeof value === "object") {
     for (const symbol of Object.getOwnPropertySymbols(value)) {
       assertNotUniqueSymbol(symbol);
@@ -195,6 +199,8 @@ export async function deserialize(
       return parseSymbol(value["@symbol"]);
     } else if ("@scope" in value) {
       return scope;
+    } else if ("@buffer" in value) {
+      return Buffer.from(value["@buffer"], "base64");
     }
 
     return Object.fromEntries(
@@ -227,3 +233,47 @@ function assertNotUniqueSymbol(symbol: Symbol) {
     throw new Error(`Cannot serialize unique symbol: ${symbol.description}`);
   }
 }
+
+export const isBinary = (
+  value: any,
+): value is Buffer | Uint8Array | ArrayBuffer | Blob | ReadableStream => {
+  return (
+    value instanceof Buffer ||
+    value instanceof Uint8Array ||
+    value instanceof ArrayBuffer ||
+    value instanceof Blob ||
+    value instanceof ReadableStream ||
+    ArrayBuffer.isView(value)
+  );
+};
+
+export const serializeBinary = async (
+  value: Buffer | Uint8Array | ArrayBuffer | Blob | ReadableStream,
+): Promise<string> => {
+  return value instanceof Buffer
+    ? value.toString("base64")
+    : value instanceof Uint8Array
+      ? value.toString("base64")
+      : value instanceof ArrayBuffer
+        ? serializeBinary(Buffer.from(value))
+        : value instanceof Blob
+          ? serializeBinary(await value.arrayBuffer())
+          : value instanceof ReadableStream
+            ? serializeBinary(await streamToBuffer(value))
+            : value;
+};
+
+export async function streamToBuffer(
+  stream: ReadableStream<Uint8Array>,
+): Promise<Buffer> {
+  const reader = stream.getReader();
+  const chunks: Uint8Array[] = [];
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    chunks.push(value);
+  }
+
+  return Buffer.concat(chunks);
+}

package/src/test/bun.ts

@@ -115,7 +115,7 @@ export function test(meta: ImportMeta, defaultOptions?: TestOptions): test {
     return afterAll(() => scope.run(() => fn(scope)));
   };
 
-  return test as test;
+  return test as any;
 
   function test(
     ...args:

package/templates/rwsdk/.cursor/rules/alchemy_cloudflare.mdc

@@ -306,7 +306,7 @@ const app = await alchemy("my-app", {
 ### Framework Integration (Vite/React/etc.)
 ```typescript
 const website = await Vite("website", {
-  main: "./src/worker.ts",
+  entrypoint: "./src/worker.ts",
   command: "bun run build", // Build command
   bindings: {
     API: await Worker("api", { entrypoint: "./api/worker.ts" }),
@@ -324,7 +324,7 @@ await alchemy.run("backend", async () => {
 });
 
 await alchemy.run("frontend", async () => {
-  await Vite("website", { main: "./src/worker.ts" });
+  await Vite("website", { entrypoint: "./src/worker.ts" });
 });
 ```
 

package/templates/tanstack-start/.cta.json

@@ -0,0 +1,13 @@
+{
+  "projectName": "@alchemy.run/tanstack-start-template",
+  "mode": "file-router",
+  "typescript": true,
+  "tailwind": true,
+  "packageManager": "bun",
+  "git": true,
+  "version": 1,
+  "framework": "react-cra",
+  "chosenAddOns": [
+    "start"
+  ]
+}

package/templates/tanstack-start/README.md

@@ -1,74 +1,292 @@
-# Welcome to TanStack.com!
+Welcome to your new TanStack app!
 
 [![Deployed with Alchemy](https://alchemy.run/alchemy-badge.svg)](https://alchemy.run)
 
-This site is built with TanStack Router!
+# Getting Started
 
-- [TanStack Router Docs](https://tanstack.com/router)
+To run this application:
+
+```bash
+bun install
+bunx --bun run start
+```
+
+# Building For Production
+
+To build this application for production:
+
+```bash
+bunx --bun run build
+```
+
+## Testing
+
+This project uses [Vitest](https://vitest.dev/) for testing. You can run the tests with:
+
+```bash
+bunx --bun run test
+```
+
+## Styling
+
+This project uses [Tailwind CSS](https://tailwindcss.com/) for styling.
+
+
+
+
+## Routing
+This project uses [TanStack Router](https://tanstack.com/router). The initial setup is a file based router. Which means that the routes are managed as files in `src/routes`.
+
+### Adding A Route
+
+To add a new route to your application just add another a new file in the `./src/routes` directory.
+
+TanStack will automatically generate the content of the route file for you.
+
+Now that you have two routes you can use a `Link` component to navigate between them.
+
+### Adding Links
+
+To use SPA (Single Page Application) navigation you will need to import the `Link` component from `@tanstack/react-router`.
+
+```tsx
+import { Link } from "@tanstack/react-router";
+```
+
+Then anywhere in your JSX you can use it like so:
+
+```tsx
+<Link to="/about">About</Link>
+```
+
+This will create a link that will navigate to the `/about` route.
+
+More information on the `Link` component can be found in the [Link documentation](https://tanstack.com/router/v1/docs/framework/react/api/router/linkComponent).
+
+### Using A Layout
+
+In the File Based Routing setup the layout is located in `src/routes/__root.tsx`. Anything you add to the root route will appear in all the routes. The route content will appear in the JSX where you use the `<Outlet />` component.
+
+Here is an example layout that includes a header:
+
+```tsx
+import { Outlet, createRootRoute } from '@tanstack/react-router'
+import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'
+
+import { Link } from "@tanstack/react-router";
+
+export const Route = createRootRoute({
+  component: () => (
+    <>
+      <header>
+        <nav>
+          <Link to="/">Home</Link>
+          <Link to="/about">About</Link>
+        </nav>
+      </header>
+      <Outlet />
+      <TanStackRouterDevtools />
+    </>
+  ),
+})
+```
+
+The `<TanStackRouterDevtools />` component is not required so you can remove it if you don't want it in your layout.
+
+More information on layouts can be found in the [Layouts documentation](https://tanstack.com/router/latest/docs/framework/react/guide/routing-concepts#layouts).
 
-It's deployed automagically with Netlify!
 
-- [Netlify](https://netlify.com/)
+## Data Fetching
 
-## Development
+There are multiple ways to fetch data in your application. You can use TanStack Query to fetch data from a server. But you can also use the `loader` functionality built into TanStack Router to load the data for a route before it's rendered.
 
-From your terminal:
+For example:
 
-```sh
-pnpm install
-pnpm dev
+```tsx
+const peopleRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: "/people",
+  loader: async () => {
+    const response = await fetch("https://swapi.dev/api/people");
+    return response.json() as Promise<{
+      results: {
+        name: string;
+      }[];
+    }>;
+  },
+  component: () => {
+    const data = peopleRoute.useLoaderData();
+    return (
+      <ul>
+        {data.results.map((person) => (
+          <li key={person.name}>{person.name}</li>
+        ))}
+      </ul>
+    );
+  },
+});
 ```
 
-This starts your app in development mode, rebuilding assets on file changes.
+Loaders simplify your data fetching logic dramatically. Check out more information in the [Loader documentation](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#loader-parameters).
 
-## Editing and previewing the docs of TanStack projects locally
+### React-Query
 
-The documentations for all TanStack projects except for `React Charts` are hosted on [https://tanstack.com](https://tanstack.com), powered by this TanStack Router app.
-In production, the markdown doc pages are fetched from the GitHub repos of the projects, but in development they are read from the local file system.
+React-Query is an excellent addition or alternative to route loading and integrating it into you application is a breeze.
 
-Follow these steps if you want to edit the doc pages of a project (in these steps we'll assume it's [`TanStack/form`](https://github.com/tanstack/form)) and preview them locally :
+First add your dependencies:
 
-1. Create a new directory called `tanstack`.
+```bash
+bun install @tanstack/react-query @tanstack/react-query-devtools
+```
+
+Next we'll need to create a query client and provider. We recommend putting those in `main.tsx`.
+
+```tsx
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+// ...
+
+const queryClient = new QueryClient();
+
+// ...
+
+if (!rootElement.innerHTML) {
+  const root = ReactDOM.createRoot(rootElement);
+
+  root.render(
+    <QueryClientProvider client={queryClient}>
+      <RouterProvider router={router} />
+    </QueryClientProvider>
+  );
+}
+```
+
+You can also add TanStack Query Devtools to the root route (optional).
+
+```tsx
+import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
+
+const rootRoute = createRootRoute({
+  component: () => (
+    <>
+      <Outlet />
+      <ReactQueryDevtools buttonPosition="top-right" />
+      <TanStackRouterDevtools />
+    </>
+  ),
+});
+```
+
+Now you can use `useQuery` to fetch your data.
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+
+import "./App.css";
+
+function App() {
+  const { data } = useQuery({
+    queryKey: ["people"],
+    queryFn: () =>
+      fetch("https://swapi.dev/api/people")
+        .then((res) => res.json())
+        .then((data) => data.results as { name: string }[]),
+    initialData: [],
+  });
+
+  return (
+    <div>
+      <ul>
+        {data.map((person) => (
+          <li key={person.name}>{person.name}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+
+export default App;
+```
+
+You can find out everything you need to know on how to use React-Query in the [React-Query documentation](https://tanstack.com/query/latest/docs/framework/react/overview).
+
+## State Management
+
+Another common requirement for React applications is state management. There are many options for state management in React. TanStack Store provides a great starting point for your project.
+
+First you need to add TanStack Store as a dependency:
 
-```sh
-mkdir tanstack
+```bash
+bun install @tanstack/store
 ```
 
-2. Enter the directory and clone this repo and the repo of the project there.
+Now let's create a simple counter in the `src/App.tsx` file as a demonstration.
 
-```sh
-cd tanstack
-git clone git@github.com:TanStack/tanstack.com.git
-git clone git@github.com:TanStack/form.git
+```tsx
+import { useStore } from "@tanstack/react-store";
+import { Store } from "@tanstack/store";
+import "./App.css";
+
+const countStore = new Store(0);
+
+function App() {
+  const count = useStore(countStore);
+  return (
+    <div>
+      <button onClick={() => countStore.setState((n) => n + 1)}>
+        Increment - {count}
+      </button>
+    </div>
+  );
+}
+
+export default App;
 ```
 
-> [!NOTE]
-> Your `tanstack` directory should look like this:
->
-> ```
-> tanstack/
->    |
->    +-- form/
->    |
->    +-- tanstack.com/
-> ```
-
-> [!WARNING]
-> Make sure the name of the directory in your local file system matches the name of the project's repo. For example, `tanstack/form` must be cloned into `form` (this is the default) instead of `some-other-name`, because that way, the doc pages won't be found.
-
-3. Enter the `tanstack/tanstack.com` directory, install the dependencies and run the app in dev mode:
-
-```sh
-cd tanstack.com
-pnpm i
-# The app will run on https://localhost:3000 by default
-pnpm dev
+One of the many nice features of TanStack Store is the ability to derive state from other state. That derived state will update when the base state updates.
+
+Let's check this out by doubling the count using derived state.
+
+```tsx
+import { useStore } from "@tanstack/react-store";
+import { Store, Derived } from "@tanstack/store";
+import "./App.css";
+
+const countStore = new Store(0);
+
+const doubledStore = new Derived({
+  fn: () => countStore.state * 2,
+  deps: [countStore],
+});
+doubledStore.mount();
+
+function App() {
+  const count = useStore(countStore);
+  const doubledCount = useStore(doubledStore);
+
+  return (
+    <div>
+      <button onClick={() => countStore.setState((n) => n + 1)}>
+        Increment - {count}
+      </button>
+      <div>Doubled - {doubledCount}</div>
+    </div>
+  );
+}
+
+export default App;
 ```
 
-4. Now you can visit http://localhost:3000/form/latest/docs/overview in the browser and see the changes you make in `tanstack/form/docs`.
+We use the `Derived` class to create a new store that is derived from another store. The `Derived` class has a `mount` method that will start the derived store updating.
+
+Once we've created the derived store we can use it in the `App` component just like we would any other store using the `useStore` hook.
+
+You can find out everything you need to know on how to use TanStack Store in the [TanStack Store documentation](https://tanstack.com/store/latest).
+
+# Demo files
+
+Files prefixed with `demo` can be safely deleted. They are there to provide a starting point for you to play around with the features you've installed.
 
-> [!NOTE]
-> The updated pages need to be manually reloaded in the browser.
+# Learn More
 
-> [!WARNING]
-> You will need to update the `docs/config.json` file (in the project's repo) if you add a new doc page!
+You can learn more about all of the offerings from TanStack in the [TanStack documentation](https://tanstack.com).