<p>When building Remix apps, you'll often need API routes for things for client-side form submissions, receiving third-party webhooks or even exposing your own API to the world. This article will show you how to do all three, with examples.</p>
<h3>API routes in Remix</h3>
<p>First, the term "API route" in Remix is somewhat of misnomer as functionally they're the same as any other route but without the <code>default export</code> of a JSX component (Remix calls these "<a href="https://remix.run/docs/en/main/guides/resource-routes">resource routes</a>"). Like other Remix routes, resource routes return a web Response object meaning you have full control over the response headers, status codes, and body content, making them perfect for APIs.</p>
<h3>Creating an API route</h3>
<p>To create an API route in Remix, you simply create a new file in the <code>routes</code> directory of your project. Let's make a basic API route that returns a JSON response:</p>
<pre><code class="language-tsx">import { json } from "@remix-run/node";

export const loader = () => {
  return json({ message: 'Hello, world!' });
};
</code></pre>
<p>Easy! Now let's make it do something useful.</p>
<h3>Client-side form submissions</h3>
<p>Sometimes you want to perform client-side form submissions without the use of Remix's <code>&#x3C;Form></code> component. Consider the following example where we have a traditional form to verify a user's email address with a verification code, with a separate button to resend the verification code if it hasn't been received.</p>
<p>Since we don't want to revalidate any data, refresh the page or navigate away from the current page, we can use <code>useFetcher</code> rather than a traditional Remix <code>&#x3C;Form></code> component to submit data directly to our API route.</p>
<pre><code class="language-tsx">import { useFetcher} from "@remix-run/react";
import { useEffect, useState } from "react";

export default function AuthVerify() {
  const formFetcher = useFetcher();
  const [errorMessage, setErrorMessage] = useState();
  const [successMessage, setSuccessMessage] = useState();

  useEffect(() => {
    if (formFetcher.data.error) {
      setErrorMessage("Error: " + formFetcher.data.error.message);
    } else {
      setSuccessMessage(formFetcher.data.message)
    }
  }, [formFetcher.data]);

  return (
    &#x3C;>
      &#x3C;VerifyEmailForm />
      &#x3C;div className={"mt-2 text-center text-sm text-muted-foreground"}>
        Didn't receive a code?{" "}
        &#x3C;button
          onClick={() => {
            formFetcher.submit(
              {},
              {
                action: "/api/verification/resend",
                method: "post",
              },
            );
          }}
          className="text-primary"
        >
          Send again
        &#x3C;/button>
        {errorMessage &#x26;&#x26; &#x3C;div className={"text-danger"}>{errorMessage}&#x3C;/div>}
        {successMessage &#x26;&#x26; &#x3C;div className={"text-success"}>{successMessage}&#x3C;/div>}
      &#x3C;/div>
    &#x3C;/>
  );
}
</code></pre>
<p>The <code>/api/verification/resend</code> route in this scenario would look something like this:</p>
<pre><code class="language-tsx">import { json } from "@remix-run/node";

export const action = async ({ request }) => {
  const userId = await getUserIdFromSession(request);
  sendSignupVerificationEmail(userId);
  return json({ message: 'Verification code sent!' });
};
</code></pre>
<blockquote>
<p>Note: Because API routes are no different to other Remix routes, they are <strong>publicly accessible</strong> and thus should always validate the appropriate permissions within</p>
</blockquote>
<h3>Receiving webhooks</h3>
<p>Another great use case for API routes is receiving webhooks from third-party services. A common example of this is receiving Stripe webhooks for checkout and subscription events.</p>
<p>The following is an example of a <code>app/routes/stripe.webhook.ts</code> file</p>
<pre><code class="language-ts">async function getStripeEvent(request) {
  // validate webhook
}

export const action = async ({ request }) => {
  const event = await getStripeEvent(request);
  const eventType = event.type;
  const data = event.data.object;
  switch (eventType) {
    case "checkout.session.completed":
      await handleCheckoutSessionCompleted(data);
      break;
    case "customer.subscription.updated":
      await handleSubscriptionUpdatedEvent(data);
      break;
    case "customer.subscription.deleted":
      await handleSubscriptionDeleted(data);
      break;
    default:
      break;
  }
  return null;
};
</code></pre>
<blockquote>
<p>Note: Again since this route is public, when receiving third-party webhooks you generally always want to validate that the event came from the official source. This process is called webhook signature verification (<a href="https://docs.stripe.com/webhooks#verify-webhook-signatures-with-official-libraries">Stripe example docs</a>)</p>
</blockquote>
<h3>Exposing an RESTful API to the outside world</h3>
<p>Sometimes you may want to offer a public API for your customers, or receive requests from a non-browser client such as a mobile app. As before, this is super easy with Remix using loaders and actions.</p>
<p>I generally always prefix these routes with <code>public</code> and add a version number to the route to make it clear that this is a public API. For example, <code>app/routes/api.public.v1.todos.ts</code>.</p>
<pre><code class="language-ts">import { json } from "@remix-run/node";
import { z } from "zod";

export const PublicApiTodoSchema = z.object({
  id: z.string(),
  title: z.string(),
  description: z.string(),
});

export const serializeIssueForApi = (todo) => {
  return PublicApiTodoSchema.parse(todo);
};

const getUserFromApiKey = async (request) => {
  const apiKeyString = request.headers.get("X-API-Key");
  return await getUserFromApiKey(apiKeyString);
};

export const loader = async ({ request }) => {
  const user = await getUserFromApiKey(request);
  if (!user) {
    return json({ message: "Invalid API key" }, { status: 401 });
  }
  const todos = await findTodosForUser(
    user.id,
  );

  const todosList = todos.map(serializeTodosForApi);
  return json({ todos: todosList });
};

export const action = async ({ request }) => {
  const user = await getUserFromApiKey(request);
  if (!user) {
    return json({ message: "Invalid API key" }, { status: 401 });
  }
  const body = await request.json();
  if (!PublicApiTodoSchema.safeParse(body)) {
    return json({ message: "Invalid request body" }, { status: 400 });
  }
  const newTodo = await createTodoForUser(user.id, body);
  return json({ todo: serializeTodoForApi(newTodo) });
};
</code></pre>
<p>Since these requests don't come from logged-in users, we authenticate them by validating API keys in the request headers. We use Zod to validate both request and response bodies, which is a good practice for all loaders and actions in general, but it's especially crucial for public APIs. Validation ensures the data matches the expected format both when saving to the database and when sending responses to clients, allowing your database model to evolve over time without breaking existing clients.</p>
<p>If we want to get really fancy, we can also use Zod to define an OpenAPI schema so that clients have automatically generated public API documentation <a href="https://fly.launchway.dev/api/public/v1/docs">like this</a>.</p>
<hr>
<p>If you're looking for a SaaS starter kit with API routes and automatically generated documentation, check out <a href="https://www.launchway.dev/">Launchway</a>. It also offers authentication, subscriptions, database connections, tons of UI components and more to get a SaaS started.</p>



When building Remix apps, you'll often need API routes for things for client-side form submissions, receiving third-party webhooks or even exposing your own API to the world. This article will show you how to do all three, with examples.

### API routes in Remix
First, the term "API route" in Remix is somewhat of misnomer as functionally they're the same as any other route but without the `default export` of a JSX component (Remix calls these "[resource routes](https://remix.run/docs/en/main/guides/resource-routes)"). Like other Remix routes, resource routes return a web Response object meaning you have full control over the response headers, status codes, and body content, making them perfect for APIs.

### Creating an API route
To create an API route in Remix, you simply create a new file in the `routes` directory of your project. Let's make a basic API route that returns a JSON response:

```tsx
import { json } from "@remix-run/node";

export const loader = () => {
  return json({ message: 'Hello, world!' });
};
```

Easy! Now let's make it do something useful.

### Client-side form submissions
Sometimes you want to perform client-side form submissions without the use of Remix's `<Form>` component. Consider the following example where we have a traditional form to verify a user's email address with a verification code, with a separate button to resend the verification code if it hasn't been received.

Since we don't want to revalidate any data, refresh the page or navigate away from the current page, we can use `useFetcher` rather than a traditional Remix `<Form>` component to submit data directly to our API route. 

```tsx
import { useFetcher} from "@remix-run/react";
import { useEffect, useState } from "react";

export default function AuthVerify() {
  const formFetcher = useFetcher();
  const [errorMessage, setErrorMessage] = useState();
  const [successMessage, setSuccessMessage] = useState();

  useEffect(() => {
    if (formFetcher.data.error) {
      setErrorMessage("Error: " + formFetcher.data.error.message);
    } else {
      setSuccessMessage(formFetcher.data.message)
    }
  }, [formFetcher.data]);

  return (
    <>
      <VerifyEmailForm />
      <div className={"mt-2 text-center text-sm text-muted-foreground"}>
        Didn't receive a code?{" "}
        <button
          onClick={() => {
            formFetcher.submit(
              {},
              {
                action: "/api/verification/resend",
                method: "post",
              },
            );
          }}
          className="text-primary"
        >
          Send again
        </button>
        {errorMessage && <div className={"text-danger"}>{errorMessage}</div>}
        {successMessage && <div className={"text-success"}>{successMessage}</div>}
      </div>
    </>
  );
}
```

The `/api/verification/resend` route in this scenario would look something like this:

```tsx
import { json } from "@remix-run/node";

export const action = async ({ request }) => {
  const userId = await getUserIdFromSession(request);
  sendSignupVerificationEmail(userId);
  return json({ message: 'Verification code sent!' });
};
```

> Note: Because API routes are no different to other Remix routes, they are **publicly accessible** and thus should always validate the appropriate permissions within

### Receiving webhooks
Another great use case for API routes is receiving webhooks from third-party services. A common example of this is receiving Stripe webhooks for checkout and subscription events.

The following is an example of a `app/routes/stripe.webhook.ts` file

```ts
async function getStripeEvent(request) {
  // validate webhook
}

export const action = async ({ request }) => {
  const event = await getStripeEvent(request);
  const eventType = event.type;
  const data = event.data.object;
  switch (eventType) {
    case "checkout.session.completed":
      await handleCheckoutSessionCompleted(data);
      break;
    case "customer.subscription.updated":
      await handleSubscriptionUpdatedEvent(data);
      break;
    case "customer.subscription.deleted":
      await handleSubscriptionDeleted(data);
      break;
    default:
      break;
  }
  return null;
};
```
> Note: Again since this route is public, when receiving third-party webhooks you generally always want to validate that the event came from the official source. This process is called webhook signature verification ([Stripe example docs](https://docs.stripe.com/webhooks#verify-webhook-signatures-with-official-libraries))

### Exposing an RESTful API to the outside world
Sometimes you may want to offer a public API for your customers, or receive requests from a non-browser client such as a mobile app. As before, this is super easy with Remix using loaders and actions.

I generally always prefix these routes with `public` and add a version number to the route to make it clear that this is a public API. For example, `app/routes/api.public.v1.todos.ts`.

```ts
import { json } from "@remix-run/node";
import { z } from "zod";

export const PublicApiTodoSchema = z.object({
  id: z.string(),
  title: z.string(),
  description: z.string(),
});

export const serializeIssueForApi = (todo) => {
  return PublicApiTodoSchema.parse(todo);
};

const getUserFromApiKey = async (request) => {
  const apiKeyString = request.headers.get("X-API-Key");
  return await getUserFromApiKey(apiKeyString);
};

export const loader = async ({ request }) => {
  const user = await getUserFromApiKey(request);
  if (!user) {
    return json({ message: "Invalid API key" }, { status: 401 });
  }
  const todos = await findTodosForUser(
    user.id,
  );

  const todosList = todos.map(serializeTodosForApi);
  return json({ todos: todosList });
};

export const action = async ({ request }) => {
  const user = await getUserFromApiKey(request);
  if (!user) {
    return json({ message: "Invalid API key" }, { status: 401 });
  }
  const body = await request.json();
  if (!PublicApiTodoSchema.safeParse(body)) {
    return json({ message: "Invalid request body" }, { status: 400 });
  }
  const newTodo = await createTodoForUser(user.id, body);
  return json({ todo: serializeTodoForApi(newTodo) });
};
```

Since these requests don't come from logged-in users, we authenticate them by validating API keys in the request headers. We use Zod to validate both request and response bodies, which is a good practice for all loaders and actions in general, but it's especially crucial for public APIs. Validation ensures the data matches the expected format both when saving to the database and when sending responses to clients, allowing your database model to evolve over time without breaking existing clients.

If we want to get really fancy, we can also use Zod to define an OpenAPI schema so that clients have automatically generated public API documentation [like this](https://fly.launchway.dev/api/public/v1/docs).

___
If you're looking for a SaaS starter kit with API routes and automatically generated documentation, check out [Launchway](https://www.launchway.dev/). It also offers authentication, subscriptions, database connections, tons of UI components and more to get a SaaS started.


Exploring different usages of API routes in Remix such as client-side form submissions, receiving webhooks, and exposing a RESTful API to the outside world.

API routes and RESTful services in Remix

<p>If you're building a Remix app you'll most likely need to handle environment variables at some point. Remix does have built-in support for loading environment variables from a system variables and <code>.env</code> files, but there's more we can do to make them type-safe, validate them at runtime, and handle them securely between server and client.</p>
<h2>Default behaviour</h2>
<p>Create a <code>.env</code> file in your project root with your environment variables:</p>
<pre><code class="language-bash"># .env
NODE_ENV=development
APP_NAME=My App
PUBLIC_SENTRY_DSN=https://xxx@xxx.ingest.sentry.io/xxx
OPENAI_API_KEY=sk-xxx
</code></pre>
<blockquote>
<p>Note: Don't forget to add <code>.env</code> to your <code>.gitignore</code> file to prevent it from being committed to your repository. In production, you'll typically set these environment variables through your hosting platform (like Vercel, Fly.io, etc.) rather than using a <code>.env</code> file.</p>
</blockquote>
<p>After this, the <a href="https://remix.run/docs/en/main/guides/envvars#server-environment-variables">docs</a> suggest exposing your environment variables to the client by adding them to your <code>window.ENV</code> object:</p>
<pre><code class="language-tsx">export async function loader() {
  return json({
    ENV: {
      PUBLIC_SENTRY_DSN: process.env.PUBLIC_SENTRY_DSN,
    },
  });
}

export function Root() {
  const data = useLoaderData&#x3C;typeof loader>();
  return (
    &#x3C;html lang="en">
    &#x3C;script
      dangerouslySetInnerHTML={{
        __html: `window.ENV = ${JSON.stringify(
          data.ENV
        )}`,
      }}
    />
    &#x3C;/html>
  );
}
</code></pre>
<p>This approach works, but has a few issues:</p>
<ol>
<li>No type safety - <code>process.env</code> does not know about the variables you've defined and will not provide any type information</li>
<li>No validation - missing or malformed variables only fail at runtime</li>
<li>No clear separation between server and client variables</li>
<li>No guarantee that sensitive information won't leak to the client</li>
</ol>
<p>Thankfully, fixing this is very simple. With the help of Zod and Typescript, we can build a robust, type-safe environment variable system that solves all the issues above.</p>
<h3>Prerequisites</h3>
<p>Install Zod in your project if you haven't already. You could also use Yup, Valibot, or another validation library if you prefer.</p>
<h3>1. Define the schema</h3>
<p>Define the schema for your environment variables using Zod. This will provide type information and validation for your environment variables. When adding a new environment variable or changing an existing one, you'll only need to update the schema here:</p>
<pre><code class="language-typescript">// utils/env.server.ts
const envSchema = z.object({
  NODE_ENV: z.enum(["production", "development", "test"] as const),
  APP_NAME: z.string(),
  
  // Public client-side vars
  PUBLIC_SENTRY_DSN: z.string().url(),
  
  // Private server-only vars
  OPENAI_API_KEY: z.string().startsWith('sk-'),
});

</code></pre>
<h3>2. Extend the <code>ProcessEnv</code> interface</h3>
<p>We can infer a Typescript type based on our Zod schema above and extend the <code>ProcessEnv</code> interface to include these variables. Doing this will give us IDE autocomplete and type checking when accessing environment variables from <code>process.env</code> in our code:</p>
<pre><code class="language-typescript">// utils/env.server.ts
export type EnvConfig = z.infer&#x3C;typeof envSchema>;

declare global {
  namespace NodeJS {
    interface ProcessEnv extends EnvConfig {}
  }
}
</code></pre>
<h3>3. Validate the environment variables</h3>
<p>At startup, we want to validate that the environment variables are correctly set to avoid any runtime errors due to missing or malformed variables. We can create a function that parses the environment variables and throws an error if they are invalid:</p>
<pre><code class="language-typescript">// utils/env.server.ts
export function parseEnv(): EnvConfig {
  const parsed = envSchema.safeParse(process.env);
  if (!parsed.success) {
    throw new Error("Invalid environment variables");
  }
  return parsed.data;
}
</code></pre>
<p>This should be called as early as possible in your app startup, e.g. in <code>entry.server.tsx</code></p>
<pre><code class="language-tsx">// entry.server.tsx
import { parseEnv } from "./utils/env.server";
import { createRequestHandler } from "@remix-run/node";

parseEnv();

export default function handleRequest(
  request: Request,
  responseStatusCode: number,
  responseHeaders: Headers,
  remixContext: EntryContext,
  loadContext: AppLoadContext,
  // ....
</code></pre>
<h3>4. Handle client-side variables</h3>
<p>To expose environment variables to the client-side code, we will create a function that returns the specific public variables we want. This function will be used in our loaders to pass the variables to the client:</p>
<blockquote>
<p>It's crucial to only expose the variables that are safe to be accessed on the client-side. Sensitive information like API keys should remain server-side only.</p>
</blockquote>
<pre><code class="language-typescript">// utils/env.server.ts
export function getPublicClientSideEnvVars() {
  return {
    NODE_ENV: process.env.NODE_ENV,
    APP_NAME: process.env.APP_NAME,
    PUBLIC_SENTRY_DSN: process.env.PUBLIC_SENTRY_DSN,
  };
}
</code></pre>
<p>Notice how we don't expose the <code>OPENAI_API_KEY</code> variable here as it's meant to be server-side only.</p>
<p>For more type-safety, we can infer another type to represent the <code>ENV</code> object that's available on the <code>window</code> object client-side:</p>
<pre><code class="language-ts">type ENV = ReturnType&#x3C;typeof getPublicClientSideEnvVars>;

declare global {
  var ENV: ENV;
  interface Window {
    ENV: ENV;
  }
}
</code></pre>
<h3>5. Inject variables into HTML</h3>
<p>Create a component to inject the public variables into your HTML. This might look wrong at first but it's the <a href="https://remix.run/docs/en/main/guides/envvars#server-environment-variables">officially recommended way</a> to expose environment variables to the client:</p>
<pre><code class="language-tsx">export const PublicEnv = (props: { env: Record&#x3C;string, string> }) => {
  return (
    &#x3C;script
      dangerouslySetInnerHTML={{
        __html: `window.ENV = ${JSON.stringify(props)}`,
      }}
    />
  );
};
</code></pre>
<p>Finally, in your root loader and component:</p>
<pre><code class="language-tsx">export async function loader({ request }: LoaderFunctionArgs) {
  return json({
    ENV: getPublicClientSideEnvVars(),
    // ... other loader data
  });
}

export function App() {
  const data = useLoaderData&#x3C;typeof loader>();
  
  return (
    &#x3C;html lang="en">
      &#x3C;head>
        {/* ... other head elements */}
      &#x3C;/head>
      &#x3C;body>
        &#x3C;PublicEnv env={data.ENV} />
        &#x3C;Outlet />
        {/* ... other body elements */}
      &#x3C;/body>
    &#x3C;/html>
  );
}
</code></pre>
<h3>6. Using the variables</h3>
<p>Now in your client-side code, you can now safely use these variables via <code>window.ENV</code> with added type-safety. Here's an example of using the Sentry DSN in your <code>entry.client.tsx</code>:</p>
<pre><code class="language-tsx">// entry.client.tsx
import * as Sentry from "@sentry/remix";
import { RemixBrowser } from "@remix-run/react";
import { StrictMode, startTransition, useEffect } from "react";
import { hydrateRoot } from "react-dom/client";

// Initialize services with type-safe client-side environment variables
Sentry.init({
  enabled: window.ENV.NODE_ENV === "production",
  dsn: window.ENV.PUBLIC_SENTRY_DSN,
  environment: window.ENV.NODE_ENV,
});

startTransition(() => {
  hydrateRoot(
    document,
    &#x3C;StrictMode>
      &#x3C;RemixBrowser />
    &#x3C;/StrictMode>,
  );
});
</code></pre>
<p>For server-side only operations, such as calling OpenAI's API, your variables are available via <code>process.env</code> as normal, but now with type-safety:</p>
<pre><code class="language-typescript">export async function action({ request }: ActionFunctionArgs) {
  // Server-side only, OpenAI key is not exposed to client
  const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
  // ...rest of your action
}
</code></pre>
<h2>Conclusion</h2>
<p>It might seem like a lot of code up front, but going forward, say when adding a new environment variable, you only need to update the Zod schema and potentially the <code>getPublicClientSideEnvVars</code> function. With this setup, you now have:</p>
<ol>
<li>Type-safety - TypeScript knows exactly what environment variables exist and their types</li>
<li>Runtime validation - Zod ensures all required variables are present and correctly formatted</li>
<li>Security - Clear separation between server-only and client-safe variables</li>
<li>DX - Better autocomplete and catch typos at compile time</li>
</ol>
<hr>
<p>If you're looking for a SaaS starter kit with this environment variable setup and more practices like this, check out <a href="https://www.launchway.dev/">Launchway</a>. It comes with authentication, subscriptions, database connections, tons of UI components and more to get your SaaS started.</p>



If you're building a Remix app you'll most likely need to handle environment variables at some point. Remix does have built-in support for loading environment variables from a system variables and `.env` files, but there's more we can do to make them type-safe, validate them at runtime, and handle them securely between server and client.

## Default behaviour

Create a `.env` file in your project root with your environment variables:

```bash
# .env
NODE_ENV=development
APP_NAME=My App
PUBLIC_SENTRY_DSN=https://xxx@xxx.ingest.sentry.io/xxx
OPENAI_API_KEY=sk-xxx
```

> Note: Don't forget to add `.env` to your `.gitignore` file to prevent it from being committed to your repository. In production, you'll typically set these environment variables through your hosting platform (like Vercel, Fly.io, etc.) rather than using a `.env` file.

After this, the [docs](https://remix.run/docs/en/main/guides/envvars#server-environment-variables) suggest exposing your environment variables to the client by adding them to your `window.ENV` object:

```tsx
export async function loader() {
  return json({
    ENV: {
      PUBLIC_SENTRY_DSN: process.env.PUBLIC_SENTRY_DSN,
    },
  });
}

export function Root() {
  const data = useLoaderData<typeof loader>();
  return (
    <html lang="en">
    <script
      dangerouslySetInnerHTML={{
        __html: `window.ENV = ${JSON.stringify(
          data.ENV
        )}`,
      }}
    />
    </html>
  );
}
```

This approach works, but has a few issues:
1. No type safety - `process.env` does not know about the variables you've defined and will not provide any type information
2. No validation - missing or malformed variables only fail at runtime
3. No clear separation between server and client variables
4. No guarantee that sensitive information won't leak to the client

Thankfully, fixing this is very simple. With the help of Zod and Typescript, we can build a robust, type-safe environment variable system that solves all the issues above.

### Prerequisites
Install Zod in your project if you haven't already. You could also use Yup, Valibot, or another validation library if you prefer. 

### 1. Define the schema

Define the schema for your environment variables using Zod. This will provide type information and validation for your environment variables. When adding a new environment variable or changing an existing one, you'll only need to update the schema here:

```typescript
// utils/env.server.ts
const envSchema = z.object({
  NODE_ENV: z.enum(["production", "development", "test"] as const),
  APP_NAME: z.string(),
  
  // Public client-side vars
  PUBLIC_SENTRY_DSN: z.string().url(),
  
  // Private server-only vars
  OPENAI_API_KEY: z.string().startsWith('sk-'),
});

```

### 2. Extend the `ProcessEnv` interface

We can infer a Typescript type based on our Zod schema above and extend the `ProcessEnv` interface to include these variables. Doing this will give us IDE autocomplete and type checking when accessing environment variables from `process.env` in our code:

```typescript
// utils/env.server.ts
export type EnvConfig = z.infer<typeof envSchema>;

declare global {
  namespace NodeJS {
    interface ProcessEnv extends EnvConfig {}
  }
}
```

### 3. Validate the environment variables

At startup, we want to validate that the environment variables are correctly set to avoid any runtime errors due to missing or malformed variables. We can create a function that parses the environment variables and throws an error if they are invalid:

```typescript
// utils/env.server.ts
export function parseEnv(): EnvConfig {
  const parsed = envSchema.safeParse(process.env);
  if (!parsed.success) {
    throw new Error("Invalid environment variables");
  }
  return parsed.data;
}
```

This should be called as early as possible in your app startup, e.g. in `entry.server.tsx`

```tsx
// entry.server.tsx
import { parseEnv } from "./utils/env.server";
import { createRequestHandler } from "@remix-run/node";

parseEnv();

export default function handleRequest(
  request: Request,
  responseStatusCode: number,
  responseHeaders: Headers,
  remixContext: EntryContext,
  loadContext: AppLoadContext,
  // ....
```

### 4. Handle client-side variables

To expose environment variables to the client-side code, we will create a function that returns the specific public variables we want. This function will be used in our loaders to pass the variables to the client:

> It's crucial to only expose the variables that are safe to be accessed on the client-side. Sensitive information like API keys should remain server-side only.

```typescript
// utils/env.server.ts
export function getPublicClientSideEnvVars() {
  return {
    NODE_ENV: process.env.NODE_ENV,
    APP_NAME: process.env.APP_NAME,
    PUBLIC_SENTRY_DSN: process.env.PUBLIC_SENTRY_DSN,
  };
}
```

Notice how we don't expose the `OPENAI_API_KEY` variable here as it's meant to be server-side only.

For more type-safety, we can infer another type to represent the `ENV` object that's available on the `window` object client-side:

```ts
type ENV = ReturnType<typeof getPublicClientSideEnvVars>;

declare global {
  var ENV: ENV;
  interface Window {
    ENV: ENV;
  }
}
```

### 5. Inject variables into HTML

Create a component to inject the public variables into your HTML. This might look wrong at first but it's the [officially recommended way](https://remix.run/docs/en/main/guides/envvars#server-environment-variables) to expose environment variables to the client:

```tsx
export const PublicEnv = (props: { env: Record<string, string> }) => {
  return (
    <script
      dangerouslySetInnerHTML={{
        __html: `window.ENV = ${JSON.stringify(props)}`,
      }}
    />
  );
};
```

Finally, in your root loader and component:

```tsx
export async function loader({ request }: LoaderFunctionArgs) {
  return json({
    ENV: getPublicClientSideEnvVars(),
    // ... other loader data
  });
}

export function App() {
  const data = useLoaderData<typeof loader>();
  
  return (
    <html lang="en">
      <head>
        {/* ... other head elements */}
      </head>
      <body>
        <PublicEnv env={data.ENV} />
        <Outlet />
        {/* ... other body elements */}
      </body>
    </html>
  );
}
```

### 6. Using the variables

Now in your client-side code, you can now safely use these variables via `window.ENV` with added type-safety. Here's an example of using the Sentry DSN in your `entry.client.tsx`:

```tsx
// entry.client.tsx
import * as Sentry from "@sentry/remix";
import { RemixBrowser } from "@remix-run/react";
import { StrictMode, startTransition, useEffect } from "react";
import { hydrateRoot } from "react-dom/client";

// Initialize services with type-safe client-side environment variables
Sentry.init({
  enabled: window.ENV.NODE_ENV === "production",
  dsn: window.ENV.PUBLIC_SENTRY_DSN,
  environment: window.ENV.NODE_ENV,
});

startTransition(() => {
  hydrateRoot(
    document,
    <StrictMode>
      <RemixBrowser />
    </StrictMode>,
  );
});
```

For server-side only operations, such as calling OpenAI's API, your variables are available via `process.env` as normal, but now with type-safety:

```typescript
export async function action({ request }: ActionFunctionArgs) {
  // Server-side only, OpenAI key is not exposed to client
  const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
  // ...rest of your action
}
```

## Conclusion
It might seem like a lot of code up front, but going forward, say when adding a new environment variable, you only need to update the Zod schema and potentially the `getPublicClientSideEnvVars` function. With this setup, you now have:

1. Type-safety - TypeScript knows exactly what environment variables exist and their types
2. Runtime validation - Zod ensures all required variables are present and correctly formatted
3. Security - Clear separation between server-only and client-safe variables
4. DX - Better autocomplete and catch typos at compile time

___
If you're looking for a SaaS starter kit with this environment variable setup and more practices like this, check out [Launchway](https://www.launchway.dev/). It comes with authentication, subscriptions, database connections, tons of UI components and more to get your SaaS started.

Handle environment variables in Remix using Zod for type-safety and validation, and separate server and client variables

Type-safe environment variables in Remix

<p>In a traditional SaaS app like you'd build with Remix, you often need to allow users to upload files. Supporting this can be tricky as there are a ton of edge cases to consider around file size, file type, and permissions.</p>
<p>In this guide, we'll walk through how to upload files in a Remix app using S3-compatible services, specifically via presigned URLs.</p>
<h3>Presigned URLs</h3>
<p><a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html">Presigned URLs</a> are URLs that grant temporary access to upload a file to a storage service. They're generated by the storage service and include all the necessary permissions and metadata for the file being uploaded. They're extremely powerful as by allowing users to upload files directly to the storage service, you never have to handle the file itself, saving you bandwidth and processing power as well as improving security.</p>
<h2>Quick demo</h2>
<p>Before diving into the guide, you can see a <a href="https://remix-s3-uploads.launchway.dev">working demo</a> of what we'll be building. This app supports switching between S3, Cloudflare and Hetzner seamlessly in a single app to show how flexible it can be.</p>
<p>The implementation is somewhat unrealistic as you probably won't need to support multiple providers like this, plus there's little validation and no real authentication or database persistence, but the principles outlined in this guide are the same.</p>
<p>If you just want the source code, check out the <a href="https://github.com/Launchway/remix-s3-uploads">repo</a>.</p>
<p><img src="/images/s3-demo.png" alt="image info"></p>
<h3>S3</h3>
<p>S3 is one of the oldest services offered by AWS and its popularity is such that other providers have made S3-compatible APIs for their own services. This means that by building off of S3, you can easily switch providers in the future if needed.</p>
<h3>Getting set up</h3>
<p>To generate presigned URLs you need a few packages:</p>
<ul>
<li><code>@aws-sdk/client-s3</code> to create the S3 client that reads and writes to storage</li>
<li><code>@aws-sdk/s3-presigned-post</code> to generate presigned POST URLs</li>
<li><code>@aws-sdk/s3-request-presigner</code> to generate presigned GET URLs (and in some cases POST URLs)</li>
</ul>
<pre><code class="language-bash">npm install @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner
</code></pre>
<p>For this guide we'll be using S3, Hetzner and Cloudflare with the AWS SDK. Initializing the client is slightly different for each:</p>
<pre><code class="language-ts">import { S3Client } from "@aws-sdk/client-s3";

// If using S3
const s3Client = S3Client({
  region: process.env.AWS_REGION,
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  },
});

// If using Cloudflare
const s3Client = S3Client({
  region: "auto",
  endpoint: process.env.CLOUDFLARE_R2_ENDPOINT,
  credentials: {
    accessKeyId: process.env.CLOUDFLARE_R2_ACCESS_KEY_ID,
    secretAccessKey: process.env.CLOUDFLARE_R2_ACCESS_SECRET_KEY,
  },
  forcePathStyle: true,
});

// If using Hetzner
const s3Client = S3Client({
  endpoint: process.env.HETZNER_ENDPOINT,
  credentials: {
    accessKeyId: process.env.HETZNER_ACCESS_KEY,
    secretAccessKey: process.env.HETZNER_SECRET_KEY,
  },
});
</code></pre>
<h3>General structure for presigned URL uploads</h3>
<p>There are three main places you'll need to interact with S3 for file uploads in a Remix app:</p>
<ol>
<li><code>loader</code> - Here you'll generate a presigned POST URL to upload the file to S3. This will be a simple JSON response with the URL and any required fields. This doesn't technically need to be a loader, and you could generate it at a later point from an API route, but for simplicity we'll use a loader here.</li>
<li><code>Form</code> - You'll need to create a form that submits to the presigned URL. This form will need to include any fields required by the presigned URL, such as the file field and any additional fields.</li>
<li><code>action</code> - After the file is uploaded to S3, you'll need to save the file details to your database. This will likely be done in an action that is called after the form is submitted.</li>
</ol>
<h3>Uploading the file (common parts)</h3>
<p>Before we dive into the specific implementations for different services, let's look at the common structure we'll use for file uploads. We'll use a traditional HTML form within our Remix component. We don't need a Remix <code>Form</code> because we're sending a request to an external service. Here's the basic structure of our <code>Upload</code> component:</p>
<pre><code class="language-tsx">export default function Upload() {
  const { presignedUrl, fields } = useLoaderData();
  const fetcher = useFetcher();

  const handleSubmit = async (event) => {
    event.preventDefault();
    const form = event.currentTarget;
    const fileInput = form.elements.namedItem("file");
    const file = fileInput.files?.[0];

    if (file &#x26;&#x26; presignedUrl) {
      // We'll implement the specific upload logic for S3/Hetzner and Cloudflare later

      // This is the same for both implementations
      const fetcherFormData = new FormData(form);
      fetcherFormData.append("key", loaderData.key);
      fetcherFormData.append("originalFileName", file.name);
      fetcher.submit(fetcherFormData, { method: "post" });
      fileInput.value = ""; // Clear the file input
    }
  };

  return (
    &#x3C;form onSubmit={handleSubmit}>
      &#x3C;input type="file" name="file" accept=".txt" />
      &#x3C;button type="submit">
        Upload to S3-compatible storage
      &#x3C;/button>
    &#x3C;/form>
  )
}
</code></pre>
<p>This component sets up the basic structure for our file upload functionality. The <code>handleSubmit</code> function will contain the logic for uploading the file, which we'll implement differently for S3/Hetzner and Cloudflare.</p>
<p>Now, let's look at the specific implementations for creating presigned URLs and uploading files for both S3/Hetzner and Cloudflare.</p>
<h2>Creating the presigned URL</h2>
<p>Let's start with the loader. This will generate a presigned URL that we can use to upload the file to S3-compatible storage.</p>
<h3>S3 and Hetzner Implementation</h3>
<h4>Creating the presigned URL</h4>
<pre><code class="language-ts">import { createPresignedPost } from "@aws-sdk/s3-presigned-post";

export const MAX_FILE_SIZE = 1 * 1024; // 1KB
export const ALLOWED_FILE_TYPES = ["text/plain"];

export const loader = async ({ request }) => {
  const session = await getSession(request);
  const userId = session.get("userId");
  
  const bucketName = process.env.UPLOADS_BUCKET_NAME!;
  const { url, fields } = await createPresignedPost(s3Client, {
    Bucket: bucketName,
    Key: key,
    Conditions: [
      // Max size
      ["content-length-range", 0, MAX_FILE_SIZE],
      // Only allow certain file types
      ["eq", "$Content-Type", ALLOWED_FILE_TYPES.join(",")],
      // Uploaded location must be prefixed with the specific user key
      ["starts-with", "$key", `user/${userId}/uploads`],
    ],
    Expires: 3600,
  });

  return {
    presignedUrl: url,
    fields,
  } 
};
</code></pre>
<p>S3 and Hetzner can use the <code>createPresignedPost()</code> method to generate URLs. This comes with a few security and permission features baked in via <code>conditions</code>:</p>
<ul>
<li>
<p><code>"content-length-range", 0, MAX_FILE_SIZE</code></p>
<p>This ensures the uploaded file will be rejected if it exceeds the maximum allowed length (in our case 1KB)</p>
</li>
<li>
<p><code>"eq", "$Content-Type", ALLOWED_FILE_TYPES.join(",")</code></p>
<p>This ensures only specific files types will be accepted (in our case <code>text/plain</code>)</p>
</li>
<li>
<p><code>"starts-with", "$key", `user/${userId}/uploads` </code></p>
<p>This is an additional security measure to ensure that the path of the uploaded file in your storage bucket is prefixed with the current user's ID. By doing this each user's files are isolated in the bucket and other user's can't upload files to other's directories</p>
</li>
</ul>
<h4>Uploading the file</h4>
<p>For S3 and Hetzner, we'll use a POST request to upload the file. Here's how we can modify the <code>handleSubmit</code> function in our <code>Upload</code> component:</p>
<pre><code class="language-tsx">const handleSubmit = async (event) => {
  // ... (previous code remains the same)

  if (file &#x26;&#x26; presignedUrl) {
    // S3/Hetzner specific upload logic
    const formData = new FormData();
    Object.entries(loaderData.fields).forEach(([key, value]) => {
      formData.append(key, value as string);
    });
    formData.set("Content-Type", file.type);
    formData.append("file", file, file.name);
    await fetch(presignedUrl, {
      method: "POST",
      body: formData,
    });

    // ... (rest of the function remains the same)
  }
};
</code></pre>
<p>This will add all of the fields generated by the <code>createPresignedPost()</code> method to the form submission, comprising the file metadata and upload URL-specific permissions.</p>
<p><em>In practice, the fields will look like the following list, but you don't need to worry too much about it:
<code>Policy</code>, <code>X-Amz-Algorithm</code>, <code>X-Amz-Credential</code>, <code>X-Amz-Date</code>,
<code>X-Amz-Signature</code>, <code>bucket</code> and <code>key</code>.</em></p>
<h3>Cloudflare Implementation</h3>
<h4>Creating the presigned URL</h4>
<pre><code class="language-ts">import { PutObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

export const ALLOWED_FILE_TYPES = ["text/plain"];

export const loader = async ({ request }) => {
  const session = await getSession(request);
  const userId = session.get("userId");
 
  const bucketName = process.env.UPLOADS_BUCKET_NAME!;

  const command = new PutObjectCommand({
    Bucket: bucketName,
    Key: key,
    ContentType: ALLOWED_FILE_TYPES[0],
  });
  const url = await getSignedUrl(s3Client, command, {
    expiresIn: 3600,
  });

  return {
    presignedUrl: url,
  } 
};
</code></pre>
<p>Cloudflare works slightly differently as it doesn't support uploading to presigned URLs via <code>POST</code> with the <code>url</code> and <code>fields</code> options. You have to generate a single URL which you eventually upload to with the <code>PUT</code> command.</p>
<h4>Uploading the file</h4>
<p>For Cloudflare, we'll use a PUT request to upload the file. Here's how we can modify the <code>handleSubmit</code> function in our <code>Upload</code> component:</p>
<pre><code class="language-tsx">const handleSubmit = async (event) => {
  // ... (previous code remains the same)

  if (file &#x26;&#x26; presignedUrl) {
    // Cloudflare specific upload logic
    await fetch(presignedUrl, {
      method: "PUT",
      body: file,
      headers: {
        "Content-Type": file.type,
      },
    });

    // ... (rest of the function remains the same)
  }
};
</code></pre>
<p>Note that this approach doesn't require the additional fields that S3 and Hetzner use.</p>
<h2>Common steps</h2>
<h3>Saving file details</h3>
<p>After the file is uploaded to the storage service, we need to save the file details in our database. By doing this you won't have to query your storage service to find the user's uploaded files. It also allows you to obfuscate the original file name in storage while preserving it's original name for presenting it to the user.</p>
<p>This step is common for both S3/Hetzner and Cloudflare implementations as we're no longer using any S3-specific functionality:</p>
<pre><code class="language-tsx">export const action = async ({ request }) => {
  const session = await getSession(request);
  const formData = await request.formData();
  const key = formData.get("key");
  const originalFileName = formData.get("originalFileName");

  // Save userId, originalFileName and key combination in database somewhere

  return json(
    { success: true },
  );
};
</code></pre>
<h2>Improving the UX</h2>
<p>Right now the only validation is done by the actual storage service, which isn't great UX. In reality you'll probably need to validate the file client-side before attempting to upload, and catching errors from the storage provider to show errors to the user if relevant.</p>
<p>This is out of scope for this article, but an example of you could implement validation on the file type and size would be in the <code>handleSubmit</code> method</p>
<pre><code class="language-ts">const handleSubmit = async (event) => {
  // ... (previous code remains the same)

  if (file &#x26;&#x26; loaderData.presignedUrl) {
    if (!ALLOWED_FILE_TYPES.includes(file.type)) {
      alert(`Only ${ALLOWED_FILE_TYPES.join(", ")} files are allowed.`);
      return;
    }
    if (file.size > MAX_FILE_SIZE) {
      alert("File size must be less than 1KB.");
      return;
    }
    // ... (rest of the function remains the same)
  }
};
</code></pre>
<p>Similarly, it's good UX to support a file upload dropzone. With a dropzone users can drag files from their file explorer into the browser window instead having to click to open the file uploader and select manually.</p>
<h2>Comparison of S3/Hetzner and Cloudflare Implementations</h2>
<p>To summarize the key differences between the S3/Hetzner and Cloudflare implementations, here's a comparison table:</p>
<p>| Feature | S3/Hetzner | Cloudflare |
|---------|------------|------------|
| Presigned URL generation | <code>createPresignedPost()</code> | <code>getSignedUrl()</code> with <code>PutObjectCommand</code> |
| Upload method | POST | PUT |
| Permissions | Granular via conditions | Limited, simpler approach |
| Form data structure | Complex (multiple fields) | Simple (file only) |
| Client-side Implementation | Requires handling multiple fields | Straightforward PUT request |
| File size/type restrictions | Server-side via conditions | Client-side validation required |</p>
<hr>
<p>If you're looking for a SaaS starter kit with S3-compatible storage, check out <a href="https://www.launchway.dev/">Launchway</a>. As well as S3-compatible storage provider for file uploads, Launchway also offers authentication, subscriptions, database connections, tons of UI components and more to get your SaaS started.</p>



In a traditional SaaS app like you'd build with Remix, you often need to allow users to upload files. Supporting this can be tricky as there are a ton of edge cases to consider around file size, file type, and permissions. 

In this guide, we'll walk through how to upload files in a Remix app using S3-compatible services, specifically via presigned URLs.

### Presigned URLs
[Presigned URLs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html) are URLs that grant temporary access to upload a file to a storage service. They're generated by the storage service and include all the necessary permissions and metadata for the file being uploaded. They're extremely powerful as by allowing users to upload files directly to the storage service, you never have to handle the file itself, saving you bandwidth and processing power as well as improving security.

## Quick demo
Before diving into the guide, you can see a [working demo](https://remix-s3-uploads.launchway.dev) of what we'll be building. This app supports switching between S3, Cloudflare and Hetzner seamlessly in a single app to show how flexible it can be. 

The implementation is somewhat unrealistic as you probably won't need to support multiple providers like this, plus there's little validation and no real authentication or database persistence, but the principles outlined in this guide are the same.

If you just want the source code, check out the [repo](https://github.com/Launchway/remix-s3-uploads). 

![image info](/images/s3-demo.png)

### S3
S3 is one of the oldest services offered by AWS and its popularity is such that other providers have made S3-compatible APIs for their own services. This means that by building off of S3, you can easily switch providers in the future if needed.

### Getting set up
To generate presigned URLs you need a few packages:
- `@aws-sdk/client-s3` to create the S3 client that reads and writes to storage
- `@aws-sdk/s3-presigned-post` to generate presigned POST URLs
- `@aws-sdk/s3-request-presigner` to generate presigned GET URLs (and in some cases POST URLs)

```bash
npm install @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-presigner
```

For this guide we'll be using S3, Hetzner and Cloudflare with the AWS SDK. Initializing the client is slightly different for each:

```ts
import { S3Client } from "@aws-sdk/client-s3";

// If using S3
const s3Client = S3Client({
  region: process.env.AWS_REGION,
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  },
});

// If using Cloudflare
const s3Client = S3Client({
  region: "auto",
  endpoint: process.env.CLOUDFLARE_R2_ENDPOINT,
  credentials: {
    accessKeyId: process.env.CLOUDFLARE_R2_ACCESS_KEY_ID,
    secretAccessKey: process.env.CLOUDFLARE_R2_ACCESS_SECRET_KEY,
  },
  forcePathStyle: true,
});

// If using Hetzner
const s3Client = S3Client({
  endpoint: process.env.HETZNER_ENDPOINT,
  credentials: {
    accessKeyId: process.env.HETZNER_ACCESS_KEY,
    secretAccessKey: process.env.HETZNER_SECRET_KEY,
  },
});
```

### General structure for presigned URL uploads
There are three main places you'll need to interact with S3 for file uploads in a Remix app:

1. `loader` - Here you'll generate a presigned POST URL to upload the file to S3. This will be a simple JSON response with the URL and any required fields. This doesn't technically need to be a loader, and you could generate it at a later point from an API route, but for simplicity we'll use a loader here.
2. `Form` - You'll need to create a form that submits to the presigned URL. This form will need to include any fields required by the presigned URL, such as the file field and any additional fields.
3. `action` - After the file is uploaded to S3, you'll need to save the file details to your database. This will likely be done in an action that is called after the form is submitted.

### Uploading the file (common parts)

Before we dive into the specific implementations for different services, let's look at the common structure we'll use for file uploads. We'll use a traditional HTML form within our Remix component. We don't need a Remix `Form` because we're sending a request to an external service. Here's the basic structure of our `Upload` component:

```tsx
export default function Upload() {
  const { presignedUrl, fields } = useLoaderData();
  const fetcher = useFetcher();

  const handleSubmit = async (event) => {
    event.preventDefault();
    const form = event.currentTarget;
    const fileInput = form.elements.namedItem("file");
    const file = fileInput.files?.[0];

    if (file && presignedUrl) {
      // We'll implement the specific upload logic for S3/Hetzner and Cloudflare later

      // This is the same for both implementations
      const fetcherFormData = new FormData(form);
      fetcherFormData.append("key", loaderData.key);
      fetcherFormData.append("originalFileName", file.name);
      fetcher.submit(fetcherFormData, { method: "post" });
      fileInput.value = ""; // Clear the file input
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input type="file" name="file" accept=".txt" />
      <button type="submit">
        Upload to S3-compatible storage
      </button>
    </form>
  )
}
```

This component sets up the basic structure for our file upload functionality. The `handleSubmit` function will contain the logic for uploading the file, which we'll implement differently for S3/Hetzner and Cloudflare. 

Now, let's look at the specific implementations for creating presigned URLs and uploading files for both S3/Hetzner and Cloudflare.

## Creating the presigned URL
Let's start with the loader. This will generate a presigned URL that we can use to upload the file to S3-compatible storage.

### S3 and Hetzner Implementation

#### Creating the presigned URL

```ts
import { createPresignedPost } from "@aws-sdk/s3-presigned-post";

export const MAX_FILE_SIZE = 1 * 1024; // 1KB
export const ALLOWED_FILE_TYPES = ["text/plain"];

export const loader = async ({ request }) => {
  const session = await getSession(request);
  const userId = session.get("userId");
  
  const bucketName = process.env.UPLOADS_BUCKET_NAME!;
  const { url, fields } = await createPresignedPost(s3Client, {
    Bucket: bucketName,
    Key: key,
    Conditions: [
      // Max size
      ["content-length-range", 0, MAX_FILE_SIZE],
      // Only allow certain file types
      ["eq", "$Content-Type", ALLOWED_FILE_TYPES.join(",")],
      // Uploaded location must be prefixed with the specific user key
      ["starts-with", "$key", `user/${userId}/uploads`],
    ],
    Expires: 3600,
  });

  return {
    presignedUrl: url,
    fields,
  } 
};
```

S3 and Hetzner can use the `createPresignedPost()` method to generate URLs. This comes with a few security and permission features baked in via `conditions`:
- `"content-length-range", 0, MAX_FILE_SIZE` 
  
  This ensures the uploaded file will be rejected if it exceeds the maximum allowed length (in our case 1KB)
- `"eq", "$Content-Type", ALLOWED_FILE_TYPES.join(",")`

  This ensures only specific files types will be accepted (in our case `text/plain`)
- ``"starts-with", "$key", `user/${userId}/uploads` ``

  This is an additional security measure to ensure that the path of the uploaded file in your storage bucket is prefixed with the current user's ID. By doing this each user's files are isolated in the bucket and other user's can't upload files to other's directories

#### Uploading the file

For S3 and Hetzner, we'll use a POST request to upload the file. Here's how we can modify the `handleSubmit` function in our `Upload` component:

```tsx
const handleSubmit = async (event) => {
  // ... (previous code remains the same)

  if (file && presignedUrl) {
    // S3/Hetzner specific upload logic
    const formData = new FormData();
    Object.entries(loaderData.fields).forEach(([key, value]) => {
      formData.append(key, value as string);
    });
    formData.set("Content-Type", file.type);
    formData.append("file", file, file.name);
    await fetch(presignedUrl, {
      method: "POST",
      body: formData,
    });

    // ... (rest of the function remains the same)
  }
};
```

This will add all of the fields generated by the `createPresignedPost()` method to the form submission, comprising the file metadata and upload URL-specific permissions.

_In practice, the fields will look like the following list, but you don't need to worry too much about it:
`Policy`, `X-Amz-Algorithm`, `X-Amz-Credential`, `X-Amz-Date`,
`X-Amz-Signature`, `bucket` and `key`._

### Cloudflare Implementation

#### Creating the presigned URL

```ts
import { PutObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

export const ALLOWED_FILE_TYPES = ["text/plain"];

export const loader = async ({ request }) => {
  const session = await getSession(request);
  const userId = session.get("userId");
 
  const bucketName = process.env.UPLOADS_BUCKET_NAME!;

  const command = new PutObjectCommand({
    Bucket: bucketName,
    Key: key,
    ContentType: ALLOWED_FILE_TYPES[0],
  });
  const url = await getSignedUrl(s3Client, command, {
    expiresIn: 3600,
  });

  return {
    presignedUrl: url,
  } 
};
```

Cloudflare works slightly differently as it doesn't support uploading to presigned URLs via `POST` with the `url` and `fields` options. You have to generate a single URL which you eventually upload to with the `PUT` command.

#### Uploading the file

For Cloudflare, we'll use a PUT request to upload the file. Here's how we can modify the `handleSubmit` function in our `Upload` component:

```tsx
const handleSubmit = async (event) => {
  // ... (previous code remains the same)

  if (file && presignedUrl) {
    // Cloudflare specific upload logic
    await fetch(presignedUrl, {
      method: "PUT",
      body: file,
      headers: {
        "Content-Type": file.type,
      },
    });

    // ... (rest of the function remains the same)
  }
};
```

Note that this approach doesn't require the additional fields that S3 and Hetzner use.

## Common steps

### Saving file details

After the file is uploaded to the storage service, we need to save the file details in our database. By doing this you won't have to query your storage service to find the user's uploaded files. It also allows you to obfuscate the original file name in storage while preserving it's original name for presenting it to the user.

This step is common for both S3/Hetzner and Cloudflare implementations as we're no longer using any S3-specific functionality:

```tsx
export const action = async ({ request }) => {
  const session = await getSession(request);
  const formData = await request.formData();
  const key = formData.get("key");
  const originalFileName = formData.get("originalFileName");

  // Save userId, originalFileName and key combination in database somewhere

  return json(
    { success: true },
  );
};
```

## Improving the UX
Right now the only validation is done by the actual storage service, which isn't great UX. In reality you'll probably need to validate the file client-side before attempting to upload, and catching errors from the storage provider to show errors to the user if relevant.

This is out of scope for this article, but an example of you could implement validation on the file type and size would be in the `handleSubmit` method

```ts
const handleSubmit = async (event) => {
  // ... (previous code remains the same)

  if (file && loaderData.presignedUrl) {
    if (!ALLOWED_FILE_TYPES.includes(file.type)) {
      alert(`Only ${ALLOWED_FILE_TYPES.join(", ")} files are allowed.`);
      return;
    }
    if (file.size > MAX_FILE_SIZE) {
      alert("File size must be less than 1KB.");
      return;
    }
    // ... (rest of the function remains the same)
  }
};
```

Similarly, it's good UX to support a file upload dropzone. With a dropzone users can drag files from their file explorer into the browser window instead having to click to open the file uploader and select manually.


## Comparison of S3/Hetzner and Cloudflare Implementations

To summarize the key differences between the S3/Hetzner and Cloudflare implementations, here's a comparison table:

| Feature | S3/Hetzner | Cloudflare |
|---------|------------|------------|
| Presigned URL generation | `createPresignedPost()` | `getSignedUrl()` with `PutObjectCommand` |
| Upload method | POST | PUT |
| Permissions | Granular via conditions | Limited, simpler approach |
| Form data structure | Complex (multiple fields) | Simple (file only) |
| Client-side Implementation | Requires handling multiple fields | Straightforward PUT request |
| File size/type restrictions | Server-side via conditions | Client-side validation required |


___
If you're looking for a SaaS starter kit with S3-compatible storage, check out [Launchway](https://www.launchway.dev/). As well as S3-compatible storage provider for file uploads, Launchway also offers authentication, subscriptions, database connections, tons of UI components and more to get your SaaS started.


A guide to handling file uploads in Remix applications using S3-compatible storage providers and presigned upload URLs

Remix file uploads using S3, Cloudflare R2 and Hetzner

<p>As you may have seen, Hezner recently announced a <a href="https://docs.hetzner.com/storage/object-storage/">S3-compatible object storage</a> offering. S3-compatible storage, also offered by the likes of Cloudflare and Backblaze, is great because you can use the same AWS SDKs you're probably familiar without being locked into any specific provider.</p>
<p>When you create a bucket in Hetzner, you get an access key and secret key which will work out of the box with things like the AWS JS SDK, but at the time of writing, there's no provided way to configure a CORS policy for the bucket. Without a CORS policy your bucket will block uploads from presigned URLs in which case you'll have to handle user-uploaded files on your API server rather than letting the user upload to the bucket directly.</p>
<p>There is a way to add the CORS policy to the bucket, however, which I'll outline here. Before starting, ensure you have a bucket already set up and have stored the access key ID and secret key somewhere safely.</p>
<h3>AWS CLI</h3>
<p>S3-compatible storage providers decide which S3 APIs they're support and thankfully Hetzner <a href="https://docs.hetzner.com/storage/object-storage/supported-actions">support plenty of them</a>. Because of this, we can use the native <a href="https://aws.amazon.com/cli/">AWS CLI</a> to perform us to perform traditional AWS S3 API commands to our Hetzner-based bucket.</p>
<p>Follow the guide in the <a href="https://docs.hetzner.com/storage/object-storage/getting-started/using-s3-api-tools">Hetzner docs</a> to get your CLI set up with your bucket credentials. At the end of it you should have files that look like this.</p>
<pre><code class="language-bash"># ~/.aws/configure
[hetzner]
endpoint_url = https://fsn1.your-objectstorage.com
</code></pre>
<pre><code class="language-bash"># ~/.aws/credentials
[hetzner]
aws_access_key_id=key-id-here
aws_secret_access_key=secret-access-key-here
</code></pre>
<p><em>Note: While the <code>endpoint_url</code> is defined in here, I couldn't get the CLI to pick it up and always have to pass the <code>--endpoint-url</code> to commands directly, but your results may vary</em></p>
<p>To test that this is working, run the following command and ensure that it works.</p>
<pre><code class="language-bash">aws s3 ls \
--endpoint-url=https://fsn1.your-objectstorage.com \
--profile hetzner
</code></pre>
<h3>CORS policy</h3>
<p>S3 allows you to <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/ManageCorsUsing.html">define your CORS policy</a> in a standard JSON format. For the sake if this demo, let's say we want to allow <code>GET</code>, <code>PUT</code>, and <code>POST</code> commands to our bucket from our web app's origin (<code>https://example.com</code>). Here's what the CORS policy for this looks like as a JSON object.</p>
<pre><code class="language-json">{
  "CORSRules": [
    {
      "AllowedOrigins": ["https://example.com"],
      "AllowedMethods": ["GET", "PUT", "POST"],
      "AllowedHeaders": [
        "Authorization",
        "Content-Type",
        "x-amz-date",
        "x-amz-content-sha256",
        "x-amz-user-agent"
      ],
      "ExposeHeaders": [
        "x-amz-server-side-encryption",
        "x-amz-request-id",
        "x-amz-id-2",
        "ETag"
      ],
      "MaxAgeSeconds": 600
    }
  ]
}
</code></pre>
<p>Save this file with, your own modifications, to a local file called <code>cors.json</code>.</p>
<h3>Applying the policy</h3>
<p>Now that we have the policy and the credentials set up, we can simply run the <a href="https://docs.aws.amazon.com/cli/latest/reference/s3api/put-bucket-cors.html"><code>put-bucket-cors</code></a> command with our Hetzner object storage credentials, and optionally the endpoint if your CLI profile doesn't pick it up, and you're done. If successful, the command will produce no output.</p>
<pre><code class="language-bash">aws s3api put-bucket-cors \
--bucket your-bucket-name \
--endpoint-url=https://fsn1.your-objectstorage.com \
--cors-configuration file://cors.json \
--profile hetzner
</code></pre>
<p>If you found this useful, please consider sharing!</p>
<hr>
<p>If you're looking for a SaaS starter kit with S3-compatible storage, check out <a href="https://www.launchway.dev/">Launchway</a>. As well as S3-compatible storage provider for file uploads, Launchway also offers authentication, subscriptions, database connections, tons of UI components and more to get a SaaS started.</p>



As you may have seen, Hezner recently announced a [S3-compatible object storage](https://docs.hetzner.com/storage/object-storage/) offering. S3-compatible storage, also offered by the likes of Cloudflare and Backblaze, is great because you can use the same AWS SDKs you're probably familiar without being locked into any specific provider.

When you create a bucket in Hetzner, you get an access key and secret key which will work out of the box with things like the AWS JS SDK, but at the time of writing, there's no provided way to configure a CORS policy for the bucket. Without a CORS policy your bucket will block uploads from presigned URLs in which case you'll have to handle user-uploaded files on your API server rather than letting the user upload to the bucket directly.

There is a way to add the CORS policy to the bucket, however, which I'll outline here. Before starting, ensure you have a bucket already set up and have stored the access key ID and secret key somewhere safely.

### AWS CLI

S3-compatible storage providers decide which S3 APIs they're support and thankfully Hetzner [support plenty of them](https://docs.hetzner.com/storage/object-storage/supported-actions). Because of this, we can use the native [AWS CLI](https://aws.amazon.com/cli/) to perform us to perform traditional AWS S3 API commands to our Hetzner-based bucket.

Follow the guide in the [Hetzner docs](https://docs.hetzner.com/storage/object-storage/getting-started/using-s3-api-tools) to get your CLI set up with your bucket credentials. At the end of it you should have files that look like this.

```bash
# ~/.aws/configure
[hetzner]
endpoint_url = https://fsn1.your-objectstorage.com
```

```bash
# ~/.aws/credentials
[hetzner]
aws_access_key_id=key-id-here
aws_secret_access_key=secret-access-key-here
```

_Note: While the `endpoint_url` is defined in here, I couldn't get the CLI to pick it up and always have to pass the `--endpoint-url` to commands directly, but your results may vary_

To test that this is working, run the following command and ensure that it works.

```bash
aws s3 ls \
--endpoint-url=https://fsn1.your-objectstorage.com \
--profile hetzner
```

### CORS policy

S3 allows you to [define your CORS policy](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ManageCorsUsing.html) in a standard JSON format. For the sake if this demo, let's say we want to allow `GET`, `PUT`, and `POST` commands to our bucket from our web app's origin (`https://example.com`). Here's what the CORS policy for this looks like as a JSON object.

```json
{
  "CORSRules": [
    {
      "AllowedOrigins": ["https://example.com"],
      "AllowedMethods": ["GET", "PUT", "POST"],
      "AllowedHeaders": [
        "Authorization",
        "Content-Type",
        "x-amz-date",
        "x-amz-content-sha256",
        "x-amz-user-agent"
      ],
      "ExposeHeaders": [
        "x-amz-server-side-encryption",
        "x-amz-request-id",
        "x-amz-id-2",
        "ETag"
      ],
      "MaxAgeSeconds": 600
    }
  ]
}
```

Save this file with, your own modifications, to a local file called `cors.json`.

### Applying the policy

Now that we have the policy and the credentials set up, we can simply run the [`put-bucket-cors`](https://docs.aws.amazon.com/cli/latest/reference/s3api/put-bucket-cors.html) command with our Hetzner object storage credentials, and optionally the endpoint if your CLI profile doesn't pick it up, and you're done. If successful, the command will produce no output.

```bash
aws s3api put-bucket-cors \
--bucket your-bucket-name \
--endpoint-url=https://fsn1.your-objectstorage.com \
--cors-configuration file://cors.json \
--profile hetzner
```

If you found this useful, please consider sharing!

---

If you're looking for a SaaS starter kit with S3-compatible storage, check out [Launchway](https://www.launchway.dev/). As well as S3-compatible storage provider for file uploads, Launchway also offers authentication, subscriptions, database connections, tons of UI components and more to get a SaaS started.


Learn how to configure CORS policies for Hetzner's S3-compatible object storage, enabling presigned URLs for direct user uploads in your web apps

Using S3 presigned upload URLs with Hetzners object storage

<p>Form validation is an essential part of web development for security, data integrity and UX. Remix offers incredibly simple means for handling forms but the guides around <a href="https://remix.run/docs/en/main/guides/form-validation">validating these forms</a> leave a lot to be desired. The official documentation and other resources propose manual validation of each field in a route's <code>action</code> handler, which can get pretty cumbersome if you have a large or complex form.</p>
<p>This is an example from the official documentation where a simple <code>email</code> and <code>password</code> form is submitted and validated on the server.</p>
<pre><code class="language-ts">export async function action({ request }) {
  const formData = await request.formData()
  const email = String(formData.get('email'))
  const password = String(formData.get('password'))

  const errors = {}

  if (!email.includes('@')) {
    errors.email = 'Invalid email address'
  }

  if (password.length &#x3C; 12) {
    errors.password = 'Password should be at least 12 characters'
  }

  if (Object.keys(errors).length > 0) {
    return json({ errors })
  }

  return redirect('/dashboard')
}
</code></pre>
<p>This will work for basic cases, but as your business requirements change over time you may add additional fields to this form or require a more complex password schema.</p>
<p>Rather than defining more rules as if-statements, a popular solution is to use something like <a href="https://zod.dev/"><code>Zod</code></a>. Zod allows you to define a schema with all of your rules so can validate input at runtime.</p>
<p>Below is the same example as above but with a Zod schema instead of manual field validation. You can see how much more robust this flow would be if we were to have password rules like requiring special characters, or numbers.</p>
<pre><code class="language-ts">const loginSchema = z.object({
  email: z.string().email('Invalid email address'),
  password: z.string().min(12, 'Password should be at least 12 characters'),
})

export async function action({ request }) {
  const formData = await request.formData()
  const rawFormData = Object.fromEntries(formData)

  const result = loginSchema.safeParse(rawFormData)

  if (result.success) {
    return redirect('/dashboard')
  } else {
    return json({ errors: result.error.flatten().fieldErrors })
  }
}
</code></pre>
<p>However, this validation still occurs entirely server-side. We have to make a round-trip to the server every time we want to validate the form and potentially return error messages. What if we could perform this validation entirely on the client-side, without any additional libraries, preventing unnecessary server requests altogether? Enter Remix's <a href="https://remix.run/docs/en/main/route/client-action"><code>clientActions</code></a>.</p>
<h2><code>clientAction</code></h2>
<p><code>clientAction</code>'s are optional handlers that run client-side before a network request is made to your server <code>action</code>. The API is almost identical to the existing server <code>action</code> you may be familiar with, with the addition of a <code>serverAction</code> property which is a method used to forward the request on.</p>
<p>The similarities of the API mean we can apply our Zod schema validation on the client-side using the same approach we use server-side.</p>
<pre><code class="language-ts">const loginSchema = z.object({
  // unchanged
})

export async function action({ request }) {
  // unchanged
}

export async function clientAction({ request, serverAction }) {
  // Clone request so the body can be reused in the action
  const clonedRequest = request.clone()
  const formData = await clonedRequest.formData()
  const rawFormData = Object.fromEntries(formData)

  const result = loginSchema.safeParse(rawFormData)
  if (result.success) {
    // If validation passes, forward the request to the server action
    return serverAction()
  } else {
    return { errors: result.error.flatten().fieldErrors }
  }
}
</code></pre>
<p>This extremely simple approach comes with some major benefits:</p>
<ul>
<li>Users get instant feedback on their input without having to wait for around-trip to the server</li>
<li>The server doesn't waste resources validating forms that we already know are invalid</li>
<li>The form validation schema can be defined once and reused used both client-side and server-side. This means no code duplication and guaranteed sync of validation rules in both places.</li>
</ul>
<h2>Wrapping up</h2>
<p>Performing client-side validation like this is an easy win as it comes out of the box with Remix. You technically don't even need Zod for this and could achieve the same by encapsulating your validation logic into a reusable method and calling it both <code>action</code> and <code>clientAction</code>.</p>
<p>It's worth mentioning here that this is <em>not a replacement</em> for server-side validation and you should always validate there before passing user input to your backend code.</p>
<p>It's also worth mentioning that are dedicated libraries for integrating Zod client-side, such as <a href="https://conform.guide/">Conform</a>, <a href="https://github.com/forge42dev/remix-hook-form">remix-hook-form</a> and <a href="https://www.remix-validated-form.io/">Remix Validated Form</a>, that offer more fine-grained control over the UX of the form and error messages. However, if you just wish to validate form input against a Zod schema, I highly recommend this simple approach.</p>
<hr>
<p>If you're looking for a SaaS starter kit with client-side validation and more practises like this, check out <a href="https://www.launchway.dev/">Launchway</a>. It also offers authentication, subscriptions, database connections, tons of UI components and more to get a SaaS started.</p>



Form validation is an essential part of web development for security, data integrity and UX. Remix offers incredibly simple means for handling forms but the guides around [validating these forms](https://remix.run/docs/en/main/guides/form-validation) leave a lot to be desired. The official documentation and other resources propose manual validation of each field in a route's `action` handler, which can get pretty cumbersome if you have a large or complex form.

This is an example from the official documentation where a simple `email` and `password` form is submitted and validated on the server.

```ts
export async function action({ request }) {
  const formData = await request.formData()
  const email = String(formData.get('email'))
  const password = String(formData.get('password'))

  const errors = {}

  if (!email.includes('@')) {
    errors.email = 'Invalid email address'
  }

  if (password.length < 12) {
    errors.password = 'Password should be at least 12 characters'
  }

  if (Object.keys(errors).length > 0) {
    return json({ errors })
  }

  return redirect('/dashboard')
}
```

This will work for basic cases, but as your business requirements change over time you may add additional fields to this form or require a more complex password schema.

Rather than defining more rules as if-statements, a popular solution is to use something like [`Zod`](https://zod.dev/). Zod allows you to define a schema with all of your rules so can validate input at runtime.

Below is the same example as above but with a Zod schema instead of manual field validation. You can see how much more robust this flow would be if we were to have password rules like requiring special characters, or numbers.

```ts
const loginSchema = z.object({
  email: z.string().email('Invalid email address'),
  password: z.string().min(12, 'Password should be at least 12 characters'),
})

export async function action({ request }) {
  const formData = await request.formData()
  const rawFormData = Object.fromEntries(formData)

  const result = loginSchema.safeParse(rawFormData)

  if (result.success) {
    return redirect('/dashboard')
  } else {
    return json({ errors: result.error.flatten().fieldErrors })
  }
}
```

However, this validation still occurs entirely server-side. We have to make a round-trip to the server every time we want to validate the form and potentially return error messages. What if we could perform this validation entirely on the client-side, without any additional libraries, preventing unnecessary server requests altogether? Enter Remix's [`clientActions`](https://remix.run/docs/en/main/route/client-action).

## `clientAction`

`clientAction`'s are optional handlers that run client-side before a network request is made to your server `action`. The API is almost identical to the existing server `action` you may be familiar with, with the addition of a `serverAction` property which is a method used to forward the request on.

The similarities of the API mean we can apply our Zod schema validation on the client-side using the same approach we use server-side.

```ts
const loginSchema = z.object({
  // unchanged
})

export async function action({ request }) {
  // unchanged
}

export async function clientAction({ request, serverAction }) {
  // Clone request so the body can be reused in the action
  const clonedRequest = request.clone()
  const formData = await clonedRequest.formData()
  const rawFormData = Object.fromEntries(formData)

  const result = loginSchema.safeParse(rawFormData)
  if (result.success) {
    // If validation passes, forward the request to the server action
    return serverAction()
  } else {
    return { errors: result.error.flatten().fieldErrors }
  }
}
```

This extremely simple approach comes with some major benefits:

- Users get instant feedback on their input without having to wait for around-trip to the server
- The server doesn't waste resources validating forms that we already know are invalid
- The form validation schema can be defined once and reused used both client-side and server-side. This means no code duplication and guaranteed sync of validation rules in both places.

## Wrapping up

Performing client-side validation like this is an easy win as it comes out of the box with Remix. You technically don't even need Zod for this and could achieve the same by encapsulating your validation logic into a reusable method and calling it both `action` and `clientAction`.

It's worth mentioning here that this is _not a replacement_ for server-side validation and you should always validate there before passing user input to your backend code.

It's also worth mentioning that are dedicated libraries for integrating Zod client-side, such as [Conform](https://conform.guide/), [remix-hook-form](https://github.com/forge42dev/remix-hook-form) and [Remix Validated Form](https://www.remix-validated-form.io/), that offer more fine-grained control over the UX of the form and error messages. However, if you just wish to validate form input against a Zod schema, I highly recommend this simple approach.

___
If you're looking for a SaaS starter kit with client-side validation and more practises like this, check out [Launchway](https://www.launchway.dev/). It also offers authentication, subscriptions, database connections, tons of UI components and more to get a SaaS started.


Exploring a novel method for client-side form validation in Remix using Zod and clientActions tp prevent unnecessary server requests

Client-side validation in Remix with Zod and clientActions

<p><a href="/blog/owning-your-app-is-good-actually">Recently</a>, I discussed the importance of "owning your app" in the Javascript ecosystem and the problems that stem from relying too heavily on third-party services and dependencies. This post focuses specifically on authentication, if you want an overview of what this series is about, I suggest you read the other article first.</p>
<hr>
<p>Authentication is a beast, arguably the most complex and error-prone part of setting up any app, and a critical aspect of truly owning your app. Fully comprehensive authentication solutions, offered by the likes of Clerk, Auth0, and Supabase, can take care of not just the actual authentication and session management but also provide social logins, password reset functionality (with emails), two-factor authentication (2FA), pre-built UI components and more. When setting up an app it can be temping to reach for one of these instead of handling everything manually in your code, but as your app grows, the real costs can start to surface.</p>
<h2>Third-party authentication services</h2>
<p>One of the biggest risks of coupling your app's authentication with a third-party service is vendor lock-in. Authentication is generally pretty central to how a web app works and if you build your base off the back of a vendor's specific API's and SDKs, it can be incredibly time-consuming, or in some cases practically impossible, to switch to a different provider or migrate to a self-hosted solution. You're essentially at the mercy of the vendor, subject to their pricing changes, feature limitations, and roadmap decisions.</p>
<p>If you're okay with the lock-in, you must also be okay with the pricing. Pretty much all authentication providers offer a free tier which, if you plan on making any money, you will eventually hit the ceiling at which point your free ride begins eating into your margins. This problem can be especially expensive if you have a free tier or if you plan on going B2C.</p>
<p>You're also completely exposed to the provider's maintenance and release cycles. By coupling your app's authentication to their service, you must update your app and its code as their APIs and SDKs develop, which can be pretty time-consuming and stressful if you have a relatively complex app. You're also exposing your users to the provider's their uptime, which in the case of authentication, can mean locking all logged-in users out of your app in the event of an outage.</p>
<p>All of these things combined can become tech debt and hugely hinder your ability to actually deliver features to your customers.</p>
<h2>"Rolling your own auth"</h2>
<p>Given these drawbacks, you might be wondering what the solution is. Enter the concept of "rolling your own auth" - a term that's often misunderstood and, in the JavaScript world, sometimes unfairly maligned.</p>
<p>The term "rolling your own auth" has traditionally been associated with implementing authentication algorithms from scratch in your code, which can be daunting and error-prone, and <strong>should be avoided</strong>. In modern web development, however, it's been redefined to mean "leveraging battle-tested authentication libraries and frameworks instead of relying on third-party services". This is a problem.</p>
<p>In traditional SSR frameworks like Laravel, Rails, and Django, "rolling your own auth" is not frowned upon and is actually the expected approach. Authentication in deeply integrated at the core of these frameworks and it's generally always the right move to choose these first-party, battle-tested libraries instead of reaching for a third-party service.</p>
<p>The JavaScript ecosystem at large, however, does <a href="https://www.youtube.com/watch?v=yaodD79Q4iE">not generally choose batteries-included frameworks</a>, instead preferring a more modular approach. The result is the authentication libraries grow somewhat separately to the frameworks themselves, spawning the likes of <a href="https://authjs.dev/getting-started/integrations"><code>Auth.js</code></a> (formerly NextAuth) and <a href="https://github.com/sergiodxa/remix-auth"><code>remix-auth</code></a>. Despite the existence of these battle-tested libraries, the concept of "rolling your own auth" in JavaScript still comes with a certain level of apprehension.</p>
<p><strong>Let me be clear: it's not as daunting as you might think, and the benefits are substantial.</strong></p>
<p>Firstly, using an off-the-shelf library allows you to own your users outright in your database. This means that you have total control over your user data and can easily migrate or switch your authentication library over time if you wanted. This is only possible with in-house authentication as <strong>the implementation and storage of your authentication are completely decoupled</strong>. If you used to use <code>Passport.js</code> and now you want to use <code>Auth.js</code>, it's possible to switch without any downtime. To go even further, you could even rewrite your app using a totally different stack and your users would be unaffected as their user information, password information and <strong>even their session information</strong> all exists in your database.</p>
<p>Owning the user information in your own database also completely removes the need to worry about Daily Active Users (DAU) or Monthly Active Users (MAU) costs as you are not bound by third-party provider fees. The cost of onboarding a new user to your app from an authentication perspective is, for all intents and purposes, zero.</p>
<p>Authentication libraries have also matured a lot over the years and have long moved past basic login and session management. <code>Auth.js</code> and <code>remix-auth</code> both support social logins (extendable to any OAuth provider), magic links, WebAuthn and 2FA. They also support handling sessions with HTTP-only cookies, rather than Javascript-readable JWTs, which is something that most of the third-party authentication services don't.</p>
<h3>A quick note on JWTs in Localstorage</h3>
<p>Javascript-readable JWTs, usually either in LocalStorage or non-HTTP-only cookies, are broadly deemed less secure than session cookies as they cannot be revoked individually without the use of a centralised table. This means if you need to quickly ban a malicious user, alter a user's permissions due to a role change, or invalidate a compromised token, you would need to wait for the token to expire naturally or force all users to log out and obtain new tokens. Managing sessions with cookies, and querying centralised sessions table on each request, nullifies all of these issues.</p>
<h3>OAuth-only authentication</h3>
<p>If you still don't fancy handling passwords, there's an even simpler approach: OAuth-only authentication. By only supporting OAuth, provided by the likes of Google, GitHub, and Facebook, you eliminate the need to store or manage passwords, removing a significant security risk, while maintaining full control over sessions and user data.</p>
<p>OAuth can also result in a simpler experience for both you (the developer) and your customers. You will end up writing less code as you no longer have to manage passwords and their adjacent functionalities (e.g. resets) and your customers won't have to remember what sign-in method they used when creating their account.</p>
<h2>Risks</h2>
<p>It wouldn't be fair to talk about in-house authentication without talking about the risks. While you aren't exposed to the risk of your third-party provider getting breached, you must still ensure it doesn't happen to you. The libraries I've mentioned will handle most of the application-level logic around implementing the cryptographic algorithms, but it's often on you to make sure you're using the library correctly and also to securely persist the data to your database. Thankfully, there are well-established rules to follow and there's plenty of guides around properly hashing and salting passwords, securely generating and storing encryption keys, and following best practices for database security.</p>
<h2>Wrapping up</h2>
<p>I'm hoping this article has helped dispel some of the myths around "rolling your own auth" and show you that it's not as scary as it may seem.</p>
<p>If you're looking for a starter kit for your next web app and you want first-party authentication, as well as emails, database integrations, payments, storage, and caching - all without any vendor lock-in - please check out <a href="https://www.launchway.dev/">Launchway</a>.</p>
<p>Alternatively if you found this at all interesting, please consider <a href="/#newsletter">signing up for the newsletter</a> or <a href="https://twitter.com/brianbriscoe_">simply following me on Twitter</a> where I rant about things like this often.</p>



[Recently](/blog/owning-your-app-is-good-actually), I discussed the importance of "owning your app" in the Javascript ecosystem and the problems that stem from relying too heavily on third-party services and dependencies. This post focuses specifically on authentication, if you want an overview of what this series is about, I suggest you read the other article first.

---

Authentication is a beast, arguably the most complex and error-prone part of setting up any app, and a critical aspect of truly owning your app. Fully comprehensive authentication solutions, offered by the likes of Clerk, Auth0, and Supabase, can take care of not just the actual authentication and session management but also provide social logins, password reset functionality (with emails), two-factor authentication (2FA), pre-built UI components and more. When setting up an app it can be temping to reach for one of these instead of handling everything manually in your code, but as your app grows, the real costs can start to surface.

## Third-party authentication services

One of the biggest risks of coupling your app's authentication with a third-party service is vendor lock-in. Authentication is generally pretty central to how a web app works and if you build your base off the back of a vendor's specific API's and SDKs, it can be incredibly time-consuming, or in some cases practically impossible, to switch to a different provider or migrate to a self-hosted solution. You're essentially at the mercy of the vendor, subject to their pricing changes, feature limitations, and roadmap decisions.

If you're okay with the lock-in, you must also be okay with the pricing. Pretty much all authentication providers offer a free tier which, if you plan on making any money, you will eventually hit the ceiling at which point your free ride begins eating into your margins. This problem can be especially expensive if you have a free tier or if you plan on going B2C.

You're also completely exposed to the provider's maintenance and release cycles. By coupling your app's authentication to their service, you must update your app and its code as their APIs and SDKs develop, which can be pretty time-consuming and stressful if you have a relatively complex app. You're also exposing your users to the provider's their uptime, which in the case of authentication, can mean locking all logged-in users out of your app in the event of an outage.

All of these things combined can become tech debt and hugely hinder your ability to actually deliver features to your customers.

## "Rolling your own auth"

Given these drawbacks, you might be wondering what the solution is. Enter the concept of "rolling your own auth" - a term that's often misunderstood and, in the JavaScript world, sometimes unfairly maligned.

The term "rolling your own auth" has traditionally been associated with implementing authentication algorithms from scratch in your code, which can be daunting and error-prone, and **should be avoided**. In modern web development, however, it's been redefined to mean "leveraging battle-tested authentication libraries and frameworks instead of relying on third-party services". This is a problem.

In traditional SSR frameworks like Laravel, Rails, and Django, "rolling your own auth" is not frowned upon and is actually the expected approach. Authentication in deeply integrated at the core of these frameworks and it's generally always the right move to choose these first-party, battle-tested libraries instead of reaching for a third-party service.

The JavaScript ecosystem at large, however, does [not generally choose batteries-included frameworks](https://www.youtube.com/watch?v=yaodD79Q4iE), instead preferring a more modular approach. The result is the authentication libraries grow somewhat separately to the frameworks themselves, spawning the likes of [`Auth.js`](https://authjs.dev/getting-started/integrations) (formerly NextAuth) and [`remix-auth`](https://github.com/sergiodxa/remix-auth). Despite the existence of these battle-tested libraries, the concept of "rolling your own auth" in JavaScript still comes with a certain level of apprehension.

**Let me be clear: it's not as daunting as you might think, and the benefits are substantial.**

Firstly, using an off-the-shelf library allows you to own your users outright in your database. This means that you have total control over your user data and can easily migrate or switch your authentication library over time if you wanted. This is only possible with in-house authentication as **the implementation and storage of your authentication are completely decoupled**. If you used to use `Passport.js` and now you want to use `Auth.js`, it's possible to switch without any downtime. To go even further, you could even rewrite your app using a totally different stack and your users would be unaffected as their user information, password information and **even their session information** all exists in your database.

Owning the user information in your own database also completely removes the need to worry about Daily Active Users (DAU) or Monthly Active Users (MAU) costs as you are not bound by third-party provider fees. The cost of onboarding a new user to your app from an authentication perspective is, for all intents and purposes, zero.

Authentication libraries have also matured a lot over the years and have long moved past basic login and session management. `Auth.js` and `remix-auth` both support social logins (extendable to any OAuth provider), magic links, WebAuthn and 2FA. They also support handling sessions with HTTP-only cookies, rather than Javascript-readable JWTs, which is something that most of the third-party authentication services don't.

### A quick note on JWTs in Localstorage

Javascript-readable JWTs, usually either in LocalStorage or non-HTTP-only cookies, are broadly deemed less secure than session cookies as they cannot be revoked individually without the use of a centralised table. This means if you need to quickly ban a malicious user, alter a user's permissions due to a role change, or invalidate a compromised token, you would need to wait for the token to expire naturally or force all users to log out and obtain new tokens. Managing sessions with cookies, and querying centralised sessions table on each request, nullifies all of these issues.

### OAuth-only authentication

If you still don't fancy handling passwords, there's an even simpler approach: OAuth-only authentication. By only supporting OAuth, provided by the likes of Google, GitHub, and Facebook, you eliminate the need to store or manage passwords, removing a significant security risk, while maintaining full control over sessions and user data.

OAuth can also result in a simpler experience for both you (the developer) and your customers. You will end up writing less code as you no longer have to manage passwords and their adjacent functionalities (e.g. resets) and your customers won't have to remember what sign-in method they used when creating their account.

## Risks

It wouldn't be fair to talk about in-house authentication without talking about the risks. While you aren't exposed to the risk of your third-party provider getting breached, you must still ensure it doesn't happen to you. The libraries I've mentioned will handle most of the application-level logic around implementing the cryptographic algorithms, but it's often on you to make sure you're using the library correctly and also to securely persist the data to your database. Thankfully, there are well-established rules to follow and there's plenty of guides around properly hashing and salting passwords, securely generating and storing encryption keys, and following best practices for database security.

## Wrapping up

I'm hoping this article has helped dispel some of the myths around "rolling your own auth" and show you that it's not as scary as it may seem.

If you're looking for a starter kit for your next web app and you want first-party authentication, as well as emails, database integrations, payments, storage, and caching - all without any vendor lock-in - please check out [Launchway](https://www.launchway.dev/).

Alternatively if you found this at all interesting, please consider [signing up for the newsletter](/#newsletter) or [simply following me on Twitter](https://twitter.com/brianbriscoe_) where I rant about things like this often.


A deep dive into the benefits and trade-offs of owning your app's authentication and offloading it to third-party services can be painful

Owning your app - Part 1: Authentication

<p>The concept of "owning your app" in the Javascript community is a lost art in 2024, and I'm here to explain why it's bad and why it matters</p>
<blockquote>
<p>Ownership: the act, state, or right of possessing something.</p>
</blockquote>
<p>In recent years, there's been a growing trend in Javascript land where, by default, core functionality and infrastructure is offloaded to third-party services and dependencies. Setting up a new project generally involves deeply coupling your database and user management to third-party services, deploying to a proprietary hosting provider, and running an app containing code from tens or hundreds of NPM packages - sometimes even for functionality like <a href="https://www.npmjs.com/package/is-number">checking if a value is a number</a>.</p>
<p>In a sense Javascript is a victim of its own success. Being extremely popular, the space moves fast, arguably too fast, which leaves little breathing room that would allow for standards and winners to emerge like you see in Python with Django or Ruby with Rails. Even if things moved slower, I don't think the community would accept a winner because sooner or later a new shiny thing would come along and become the new state of the art. Long gone are the days of jQuery and MooTools being the "one true way" to write Javascript apps.</p>
<p>The reason I think this is bad is it results in a <strong>lack of ownership</strong>.</p>
<p>Let me clarify that I am <strong>not suggesting that you write all functionality from scratch</strong> every time you write an app. Some usage of third-party services, packages and hosting providers are an essential part of writing a Javascript app in 2024 and I think abundance of options in these areas are one of the ecosystem's strengths.</p>
<p>My issue lies with the willingness of the Javascript community, spurred on by VC-backed DevRels and other influencers, to default to reaching for an off-the-shelf solution for functionality that could be easily written and owned within your app code.</p>
<p>Every time you choose to add a dependency for something you could have written yourself, you're making a bet. A bet that the library maintainer won't <a href="https://www.sonatype.com/blog/npm-libraries-colors-and-faker-sabotaged-in-protest-by-their-maintainer-what-to-do-now">sabotage the package</a> you use due to a lack of funding, a bet that your VC-backed database provider won't <a href="https://planetscale.com/docs/concepts/hobby-plan-deprecation-faq">rug-pull their free tier so they can focus on enterprise</a>, a bet that your app hosting provider wont <a href="https://portswigger.net/daily-swig/heroku-resets-user-passwords-after-concluding-april-cyber-attack-ran-deep">get hacked and request you change all of your secrets</a>, or that your auth provider won't ship a <a href="https://dev.to/emmanuelthecoder/recent-security-vulnerability-detected-in-clerk-should-you-roll-your-own-auth-52l1">critical security vulnerability</a>.</p>
<p>By delegating too much ownership to external vendors, you're not only risking security and stability but you also lose the agility to pivot and adapt your app as needed. The end-game of this approach is being so locked into proprietary database features, platform-specific APIs, and third-party dependencies that any significant change can become a major overhaul rather than a manageable update.</p>
<p>The path to regaining control of your Javascript app doesn't mean rejecting all third-party services altogether, rather carefully choosing which parts of your app you should own outright. In the upcoming series, I'll dig deeper into the specifics of owning various parts of your app. Specifically, I'll focus on what I feel are the areas where ownership is the most important</p>
<ul>
<li>Authentication</li>
<li>Infrastructure</li>
<li>Code</li>
</ul>
<p>By taking a critical look at these areas and figuring out where it makes sense to maintain ownership, you can write Javascript applications that are built for the future. If this is something you'd be interested in, please <a href="/#newsletter">sign up for the newsletter</a> or <a href="https://twitter.com/brianbriscoe_">follow me on Twitter</a></p>



The concept of "owning your app" in the Javascript community is a lost art in 2024, and I'm here to explain why it's bad and why it matters

> Ownership: the act, state, or right of possessing something.

In recent years, there's been a growing trend in Javascript land where, by default, core functionality and infrastructure is offloaded to third-party services and dependencies. Setting up a new project generally involves deeply coupling your database and user management to third-party services, deploying to a proprietary hosting provider, and running an app containing code from tens or hundreds of NPM packages - sometimes even for functionality like [checking if a value is a number](https://www.npmjs.com/package/is-number).

In a sense Javascript is a victim of its own success. Being extremely popular, the space moves fast, arguably too fast, which leaves little breathing room that would allow for standards and winners to emerge like you see in Python with Django or Ruby with Rails. Even if things moved slower, I don't think the community would accept a winner because sooner or later a new shiny thing would come along and become the new state of the art. Long gone are the days of jQuery and MooTools being the "one true way" to write Javascript apps.

The reason I think this is bad is it results in a **lack of ownership**.

Let me clarify that I am **not suggesting that you write all functionality from scratch** every time you write an app. Some usage of third-party services, packages and hosting providers are an essential part of writing a Javascript app in 2024 and I think abundance of options in these areas are one of the ecosystem's strengths.

My issue lies with the willingness of the Javascript community, spurred on by VC-backed DevRels and other influencers, to default to reaching for an off-the-shelf solution for functionality that could be easily written and owned within your app code.

Every time you choose to add a dependency for something you could have written yourself, you're making a bet. A bet that the library maintainer won't [sabotage the package](https://www.sonatype.com/blog/npm-libraries-colors-and-faker-sabotaged-in-protest-by-their-maintainer-what-to-do-now) you use due to a lack of funding, a bet that your VC-backed database provider won't [rug-pull their free tier so they can focus on enterprise](https://planetscale.com/docs/concepts/hobby-plan-deprecation-faq), a bet that your app hosting provider wont [get hacked and request you change all of your secrets](https://portswigger.net/daily-swig/heroku-resets-user-passwords-after-concluding-april-cyber-attack-ran-deep), or that your auth provider won't ship a [critical security vulnerability](https://dev.to/emmanuelthecoder/recent-security-vulnerability-detected-in-clerk-should-you-roll-your-own-auth-52l1).

By delegating too much ownership to external vendors, you're not only risking security and stability but you also lose the agility to pivot and adapt your app as needed. The end-game of this approach is being so locked into proprietary database features, platform-specific APIs, and third-party dependencies that any significant change can become a major overhaul rather than a manageable update.

The path to regaining control of your Javascript app doesn't mean rejecting all third-party services altogether, rather carefully choosing which parts of your app you should own outright. In the upcoming series, I'll dig deeper into the specifics of owning various parts of your app. Specifically, I'll focus on what I feel are the areas where ownership is the most important

- Authentication
- Infrastructure
- Code

By taking a critical look at these areas and figuring out where it makes sense to maintain ownership, you can write Javascript applications that are built for the future. If this is something you'd be interested in, please [sign up for the newsletter](/#newsletter) or [follow me on Twitter](https://twitter.com/brianbriscoe_)


A brief critique on the state of Javascript apps in 2024 and the problems with offloading everything to third-party services

Blog