Remix

Learn how to deploy your Remix v2 project to your own cloud infrastructure with Ownstak.

note

Remix v2 is no longer receiving any updates. The Remix project was renamed to React Router v7 with similar API. If you're starting a new OwnStak project, please use React Router v7 instead. Please see the React Router guide and Upgrade guide for existing projects.

Prerequisites

• An Ownstak account with a fully set up organization
• A Remix project (version 2.x.x)
• Node.js installed locally (version 18.x or higher)

Getting Started

1. Prepare your React Router project

Create a new Remix v2 project by running:

npx create-remix@2.16.8

Once the wizard finishes, enter the project directory and install all dependencies:

cd your-remix-project
npm install

note

For existing projects, remove any provider-specific dependencies, such as @remix-run/cloudflare, from vite.config.js and install generic @remix-run/node package together with @remix-run/dev.

2. Configure your project

Remix can be built in two modes:

• Vite Builder (npx remix vite:build)

  The Vite builder is the default and recommended approach. OwnStak will automatically use the Vite builder if it detects a vite.config.js file in your project.
  OwnStak is able to read customized buildDirectory, serverBuildFile, basename, and other Remix Vite plugin config options, but it's recommended to keep them at their defaults for optimal compatibility. No specific config is required for OwnStak.

  vite.config.js

  import { vitePlugin as remix } from "@remix-run/dev";
  import { defineConfig } from "vite";
  
  export default defineConfig({
    plugins: [
      remix({
        // buildDirectory: "build",
        // serverBuildFile: "index.js",
        // basename: "/",
      }),
    ],
  });

• Classic Builder (npx remix build)

  If no vite.config.js is found, OwnStak will use the classic Remix builder.

  remix.config.js

  export default {
      // assetsBuildDirectory: 'public/build'
      // serverBuildPath?: 'build/index.js';
      // publicPath: '/build/';
  };

3. Deploy from your machine

Now, you can deploy the project from your machine by running:

npx ownstak deploy

When you run the deploy command for the first time, the CLI will detect the currently used framework and guide you through the login and project configuration setup. Simply follow the instructions:

The organization and project names are stored in the ownstak.config.js configuration file for subsequent deployments, so you won't be prompted for this information again.

4. Deploy from CI

For CI and other non-persistent environments, you can skip the interactive deployment by providing the API key and other required options as command arguments. You can generate a new API key for your account or project in the Ownstak Console under Settings > API Keys.

npx ownstak deploy --api-key=<your-secret-key> --organization=ownstak --project=ownstak-remix --environment=default

5. Done!

Your project is now live and deployed to your organization's cloud infrastructure. You can visit and test it using the environment and deployment links provided in the output:

• Environment link – Always points to the latest deployment in a given project environment Example: my-remix-app-development.aws-primary.my-org.ownstak.link
• Deployment link – Always points to a specific deployment Example: my-remix-app-development-10.aws-primary.my-org.ownstak.link

Local testing

If your project doesn't behave as expected, you can build and test it locally before deploying.

1. Build the project

Run the following command in your project directory to build your project without deploying it:

npx ownstak build

2. Start the project

Start the project and make sure it works for you locally with Ownstak:

npx ownstak start

When you see the ready message, you can visit `

Custom Express server

OwnStak runs Remix projects with a preconfigured HTTP server by default. If you would like to run Remix with Express or any other custom server, you can provide a custom entrypoint file. Here's how:

1. Install @remix-run/express

npm i @remix-run/express@2.16.8 express

2. Create custom server file

Create your custom server entrypoint file server.mjs in the root of your project that imports the Remix build output. Here's an example:

server.mjs

import { dirname, join } from 'path';
import { fileURLToPath } from 'url';
import { createRequestHandler } from "@remix-run/express";
import express from "express";

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

const PORT = Number(process.env.PORT || 3000);
const HOST = process.env.HOST || '0.0.0.0';

const app = express();

app.use(
  createRequestHandler({
    // The relative path to the build output
    build: await import(join(__dirname, "build/index.js")),
  }),
);

app.listen(PORT, HOST, () => {
  console.log(`Server is running on http://${HOST}:${PORT}`);
});

3. Update the OwnStak config

Update the default entrypoint for Remix in your ownstak.config.js file with your Express server by calling setAppEntrypoint("./server.mjs") option and tell the OwnStak to trace and copy all the dependencies by calling setCopyAppDependencies(true).

ownstak.config.js

import { Config } from 'ownstak';

export default new Config()
  .setAppEntrypoint("./server.mjs")
  .setCopyAppDependencies(true)

4. Build OwnStak

npx ownstak build

5. Test changes locally

npx ownstak start

6. Done

The project is ready to be deployed!