Can I run one-time code at vite server start without a custom server?

[maranomynet]

Is it possible to run some environment validation code as the built-in Remix server starts?

I'm using the vite plugin and I'd like to avoid the maintenence burden of remix revealing a entry.server.tsx, and I don't otherwise need a custom server.

Related, but uses custom server: #8694

[kiliman]

Although doable, it's kind of tricky due to the fact the development and production builds are different. In DEV mode, Vite is responsible for the web server. Whereas in PROD, we are using Remix App Server, and it uses the build output from Vite remix vite:build.

So, to tackle Vite DEV, I created a serviceStartup plugin that will let you pass in a set of services to start.

I created a folder app/startup with the startup functions.

// vite.config.ts
import serviceStart from "./app/startup/service";
import anotherServiceStart from "./app/startup/another-service";

installGlobals();

export default defineConfig({
  plugins: [
    serviceStartup({
      "my-service": serviceStart,
      "another-service": anotherServiceStart,
    }),
    remix(),
    tsconfigPaths(),
  ],
});

type ServicesType = Record<string, () => void>;

function serviceStartup(services: ServicesType) {
  const serviceStatus = new Map<string, boolean>();
  return {
    name: "service-startup",
    configureServer(server: { config: { appType: string; mode: string } }) {
      // remix vite does two builds, so only start services for custom SSR
      if (
        server.config.mode === "development" &&
        server.config.appType === "custom"
      ) {
        Object.entries(services).forEach(([name, startFunction]) => {
          // check if service already started
          if (serviceStatus.get(name)) return;
          console.log(`starting service: ${name}`);
          startFunction();
          console.log();
          serviceStatus.set(name, true);
        });
      }
    },
  };
}

// app/startup/service.ts
export default function start() {
  console.log("service started!");
}

// app/startup/another-service.ts
export default function start() {
  console.log("another service started!");
}

This should start all the services when the Vite DEV server initializes.

Now, for a PROD build, we can't update RAS, and you don't want entry.server.tsx. So, the next best place is the root.tsx route.

Add this to your root route, and it will start the services on startup.

// app/root.tsx
import serviceStart from "~/startup/service";
import anotherServiceStart from "~/startup/another-service";

function start() {
  console.log("starting services from root");
  serviceStart();
  anotherServiceStart();
}
// only run this in production, since Vite handles startup in development
if (process.env.NODE_ENV === "production") {
  start();
}

Normally we could just add this to root and it'll work in both DEV and PROD, but Vite doesn't execute the root route until the first request.

[maranomynet]

<peeve>
There are so many Remix guidelines that casually involve maintaining custom entry.server.tsx and entry.client.tsx, or a custom server.ts just to add a single line of extra logic.

The entry.*.tsx files, especially, are large and full of code that seems to be evolving/changing with each release of Remix.

I'd LOVE to see Remix (or the vite plugin) provide more of a middle-ground between "pure default behavior" and "go maintain your own request handler".
</peeve>

[maranomynet]

But other route exports in 'app/root.tsx' depend on './env.server'.

Just to be clear: There's no exported code in root.tsx that references anything inside ./env.server in any way whatsover.

And this is env.server.ts:

import { TypeOf, z } from 'zod';

// Ensure at runtime that all required environment variables are defined.
const url = /*#__PURE__*/ z.string().url();
const str = /*#__PURE__*/ z.string().min(1);

const envFileSchema = /*#__PURE__*/ z.object({
  API_HOST: url,
  API_KEY: str,
});

declare global {
  namespace NodeJS {
    interface ProcessEnv extends Readonly<TypeOf<typeof envFileSchema>> {}
  }
}

const checkEnv = () => {
  try {
    envFileSchema.parse(process.env);
  } catch (err) {
    if (err instanceof z.ZodError) {
      const { fieldErrors } = err.flatten();
      const errorMessage = Object.entries(fieldErrors)
        .map(([field, errors]) => (errors ? `${field}: ${errors.join(', ')}` : field))
        .join('\n  ');
      const pluralSuffix = Object.keys(fieldErrors).length > 1 ? 's' : '';
      throw new Error(`Missing environment variable${pluralSuffix}:\n  ${errorMessage}`);
      process.exit(1);
    }
  }
};

/*#__PURE__*/ checkEnv();

(I added the "PURE" markers in case it might help the treeshaker's confidence.)

[maranomynet]

I'm tempted to add a TS-to-JS build step to transpile env.server.ts as a standalone script and then run it before envoking remix-serve ./build/server/index.js.

It's just more faffin than I was hoping for.

[kiliman]

Ok, I figured out a solution. Install the Vite plugin vite-env-only by @pcattori.

npm install vite-env-only

Update your vite.config.ts file to add the plugin.

// vite.config.ts
import envOnly from "vite-env-only";

export default defineConfig({
  plugins: [envOnly(), remix(), tsconfigPaths()],
});

Export your checkEnv function

// env.server.ts
export const checkEnv = () => {
  console.log("checking env");
};

Then in your root, import the function and wrap in serverOnly$ call

// root.tsx
import { serverOnly$ } from "vite-env-only";
import { checkEnv } from "./env.server";
serverOnly$(checkEnv());

This will call checkEnv() at startup for production builds, and on first route access for development.

[maranomynet]

Ah! serverOnly$ ...of course!

Curses for not figuring this out on my own.

Thanks!

[davidsonsns]

hey @kiliman, thanks so much for providing such a detailed explanation. Was looking for this for a while, you helped me a lot.

question: I have exactly the same structure, but for some reason it's not calling checkEnv on startup in production. not sure if this is a remix version thing (installed version 2.8.1). any guesses?

btw, vite-env-only version 3.0.1 changed envOnly to envOnlyMacros. this could be the reason why I'm having another experience (not sure if the core of this function was revamped)

[bocajji]

A little late to the party, but what about verifying the environment variables in a separate script before starting the app? That way you avoid the issues of when verification is actually called when starting the remix server.

for example in package.json:

    "verify-env-vars": "node scripts/your-env-verification-script.js",
     "dev": "npm run verify-env-vars && remix vite:dev"

[gustavopch]

Here, I do it like env('MY_VAR') and this function throws if it's required but missing.

[maranomynet]

Yes this is more feasible now that Remix/react-router works with bun, and node.js can be coerced into running .ts files directly.

In fact I think I will update my projects to do that.

Before, this would have required a transpilation step, or maintaining a separate JavaScript env validation module (providing no type safety).