App Configuration

The sherpa.sh platform supports many different types of frameworks using the same simple settings. Below are the most common settings you need to set to deploy your web app.

Default Domain

This is the domain where you're application will be reachable by your users. It is fully customizable.

By default, your web app will be assigned a subdomain under sherpa.software. This is the address where users can access your application. For example, if your app is named "myapp," it will default to myapp.sherpa.software.

You can always change this domain to suit your preferences, or use a custom domain.

Build Settings

There are different build settings depending on what type of app you are building:

• View Javascript Build Settings
• View Docker Build Settings

Javascript Applications

The commands that are run when building the production version of your app. Typically, these are the install and build commands in your package.jsonfile.

You can use the following support package managers:

• npm
• pnpm
• yarn
• bun

Need something else? Let us know.

Framework

Select your projects framework. When your app is deployed we use your framework's best practices to optimize the infrastructure for your application. This means we setup all the appropriate cache-headers, distributed caching, and scaling algorithms to ensure a fast, delightful, and personalized customer experience.

If the framework you need is not listed or supported, let us know, we'll add it faster than you think!

Install Command

How you install your node modules and packages. Typically this is a command from your package.json. For example: npm i.

Tip

Your project is installed into a Linux container with a litany of standard binaries.
Learn more about our container runtime.

Build Command

How you build your project. Like npm run build. We set NODE_ENV=production by default for all builds of javascript applications. You can override this with environment variables.

Note

Supporting .mjs files: Your project must support .mjs file types. If you have this disabled via eslint or typescript rules, you will need to enable it for your builds to complete.

If you are unsure, you likely do not need to worry about this. Most modern JS frameworks enforce this by default.

Output Directory

The path where your build command outputs the built files Usually you want to leave this as the default value.

If you run into trouble, open a chat with us and we'll be happy to help you get setup.

Note

If your app folder is nested in a repo subfolder, you want to use the root directory setting to set that folder, not the output directory.

Static Generation Only

When this is toggled on, Sherpa.sh will build and deploy your project using SSG (Static Site Generation). You must ensure that your project is configured appropriately, and the correct output directory is set for your deployment.

Caution

Some frameworks require you to explicitly set the build process for SSG in your codebase. For example, in Next.js projects you must have output: export set in your next.config.ts/js . Not doing so could result in failed deployments or unexpected behavior.

Docker Applications

Docker Settings

Two different settings are essential for Docker applications:

• Dockerfile: The name of the Dockerfile to build your application. If your docker file is not named Dockerfile this is where you put that value.
• Port: The port that your application exposes. Set the value of the exposed port that the application listens to in the container. This can only be one port. If you have multiple services that run on different ports please put them in separate containers. If they are in the same repo, you can import the repository twice and set different Dockerfile settings.

Root Directory

Sometimes your application will be in a sub-directory of your repo. Set this value to the directory path of your application in your repo. For example if you have a NextJS app inside of your repo in the path root > projects > mynextapp , in the root directory setting you would put the value projects/mynextapp.

All Build Setting commands will run inside this folder.

Environment Variables

Environment variables are key-value pairs accessible via process.env in your Node.js application, both during build and runtime.

Processing Conventions

Our platform processes environment variables through a specific pipeline:

1. Adding Variables: Environment variables added in the gui (including pasting .env files) are parsed into JSON using dotenv and saved securely in the Sherpa.sh infrastructure.
2. Building Process Access to Variables: At build time, variables are written to a file in your build directory called .env.local and loaded into the bash environment along with any other .env files in your repo via dotenvx (See resolution order below for variables resolution with multiple .env files). Additionally, NODE_ENV defaults to production unless explicitly set.
3. Application Access to Variables: At deployment time, the environment variables JSON is converted to YAML via js-yaml and injected into the Docker container environment. These env variables are available in the OS for your backend application. Additionally, the .env.local file written during the build process will ensure all environment variables are available in the process.env of your application (based on your frameworks conventions for injecting variables into process.env these will be avaiable in both the frontend and backend)

Caution

Be cautious with the variables you expose to your application’s frontend. Framework-specific prefixes expose variables to client-side code:

• Next.js: NEXT_PUBLIC_*
• Vite: VITE_*
• Create React App: REACT_APP_*

Never expose API keys, database credentials, or secrets through these prefixes. Always ensure sensitive data remains secure and is not included in these public-facing variables. Please refer to your framework's documentation for more info.

Resolution Order

Standard Projects (Non-Next.js)

Following dotenv-flow conventions, files are loaded in priority order:

1. .env.{NODE_ENV}.local (e.g., .env.production.local)
2. .env.local (ignored when NODE_ENV=test) *^{Added by Sherpa.sh with your env vars.}
3. .env.{NODE_ENV} (e.g., .env.production)
4. .env

Next.js Projects

Following Next.js conventions:

1. process.env
2. .env.$(NODE_ENV).local
3. .env.local (not loaded when NODE_ENV=test) *^{Added by Sherpa.sh with your env vars.}
4. .env.$(NODE_ENV)
5. .env

Formatting

Note

Note: Because your app will be deployed with Docker, environment variable keys that are valid in .env files may be stripped when saved to ensure Docker/Kubernetes compatibility. See Valid Keys Below.

Special Characters

Based on dotenv parsing behavior, here's how special characters are interpreted and made available to process.env:

Character/Pattern	Input	process.env output	Notes
Newlines	"Line1\nLine2"	Line1\nLine2	\n becomes actual newline
Escaped newlines	"Line1\\nLine2"	Line1\\nLine2	\\n preserved as literal
Carriage returns	"Line1\r\nLine2"	Line1\r\nLine2	Windows line endings preserved
Quotes in values	"This is \"quoted\""	This is \"quoted\"	Escape sequences preserved
Dollar signs	'$HOME won't expand'	$HOME won't expand	Single quotes prevent expansion
Backslashes	"C:\path\to\file"	C:\path\to\file	Single backslash preserved
Double backslashes	"C:\\path"	C:\\path	Literal backslashes
Special escapes	"\t \r \n"	Tab, CR, LF characters	Escape sequences interpreted
Multiline actual	"Line1 Line2"	Line1\nLine2	Actual line breaks become \n
Comments	value # comment	value	Comments stripped
Leading/trailing spaces	` value `	value	Spaces trimmed unless quoted

Valid Keys

Environment variables must be compatible with Kubernetes naming conventions since they're deployed to Docker containers. Keys are validated against the pattern: [-._a-zA-Z][-._a-zA-Z0-9]*

Filtered Keys (automatically removed):

• Starting with numbers: 123KEY, 1_VARIABLE
• Containing spaces: MY KEY, VARIABLE NAME
• Special characters: KEY@EMAIL, KEY#HASH, KEY$DOLLAR, KEY-WITH-DASH
• Dots in names: KEY.WITH.DOT, app.config.value

Valid Keys:

• Alphanumeric with underscores: API_KEY, DATABASE_URL, PORT_3000
• Starting with letters: MY_VAR, abc123
• Starting with underscore: _PRIVATE, __INTERNAL__
• Mixed case: MyVariable, camelCase

Tip

Securing Credentials: We follow security best-practices for securing your environment variables. Environment variables are stored on a secure server. Access is controlled with extremely limited RBAC. Credentials are only gathered on a as-needed basis to build your project. Otherwise they are always stored securely at rest.

This approach ensures that no unauthorized sherpa.sh employees can view your secrets.

App Region

When configuring your app region, you can choose from three options:

• US East (N. Virginia),
• US West (N. California)
• EU Central (Frankfurt, Germany).

This selection determines where your application will run. You want to select the location closest to your database(s) to minimize latency to and from your data.

For more information, see our regions documentation.

Note

Depending on your project's setup, many requests will hit your content cached on our global CDN and not your application - for example with partial pre-renders, cached content will exist on the network edge and your application will do minimal work to service the request.

For further info on the architecture, please refer to our architecture documentation.

NodeJS Version

The version of Node to use for the build process and for running your application.

Branch Settings

Configure how continuous delivery works on your application.

The selected branch will be the production branch, meaning any new commit on that branch will trigger a build and deployment to your Default Domain.

A build and deployment to a preview environment will also be triggered when a new pull request is opened for a different branch. New commits on branches with open pull requests will also trigger a new build and deployment to a preview environment. You can disable automatic deployments of preview branches by disabling auto branch deployments.