Skip to main content

Project Configuration

Discover all available project configuration options that can be specified inside ownstak.config.mjs

The Ownstak configuration file (ownstak.config.mjs) allows you to customize how your project is built, deployed and store this config together with your project source code. This file should be placed in your project's root directory. If no file is found, the CLI uses default or auto-detected values.

You can create a new config for your project by running:

npx ownstak config init

This command will launch a wizard to guide you through the setup. Other supported file names include ownstak.config.js, ownstak.config.cjs, and ownstak.config.ts.

Basic Example​

Here's a basic example of an Ownstak configuration file:

ownstak.config.mjs
import { Config } from 'ownstak';

export default new Config()
  .setOrganization("my-org")
  .setProject("my-next-app")
  .setRuntime("nodejs22.x")
  .setArch("arm64");

The configuration file is evaluated only once at build time, which means you can configure it programmatically or use environment variables from your CI/CD pipelines in it:

ownstak.config.mjs
import { Config } from 'ownstak';

export default new Config().setRuntime(process.env.OWNSTAK_RUNTIME)

Available Options​

project​

The name of your project. This name is later displayed in the OwnStak Console. By default, the project name from package.json is used. If the project doesn't exist in the given organization, the CLI will create it on deploy.

  • Type: string
  • Default: Name from package.json or 'default'
  • Setter: .setProject(name: string)

organization​

The name of your organization in the OwnStak Console. The organization needs to exist; otherwise, deployment fails.

  • Type: string
  • Setter: .setOrganization(name: string)

environment​

The environment name for your deployment that is later also displayed in the OwnStak Console. Defaults to default. If the environment doesn't exist in the given organization and project, the CLI will create it on deploy.

  • Type: string
  • Default: 'default'
  • Setter: .setEnvironment(name: string)

runtime​

The Node.js runtime version to use for your application.

  • Type: string
  • Default: Automatically selected based on your local Node.js version
  • Supported Values: 'nodejs18.x', 'nodejs20.x', 'nodejs22.x'
  • Setter: .setRuntime(runtime: string)

memory​

The amount of RAM (in MiB) to allocate to your application.

  • Type: number
  • Default: 1024
  • Range: 1–10240 MiB
  • Setter: .setMemory(sizeInMiB: number)

arch​

The CPU architecture to use for your application.

  • Type: string
  • Default: Automatically selected based on your local architecture
  • Supported Values: 'x86_64', 'arm64'
  • Setter: .setArch(architecture: string)

timeout​

The maximum execution time (in seconds) for your application.

  • Type: number
  • Default: 20
  • Range: 1–900 seconds
  • Setter: .setTimeout(durationInSeconds: number)

framework​

The framework to use for your application.

  • Type: string
  • Default: Auto-detected framework
  • Supported Values: 'nextjs', 'astrojs', 'static'
  • Setter: .setFramework(framework: string)

frameworkAdapter​

The framework adapter that defines how to build and deploy your application. The CLI comes with predefined adapters for supported frameworks, but this option allows you to write your own or tweak the existing behavior.

  • Type: object
  • Default: Auto-detected framework adapter
  • Setter: .setFrameworkAdapter(adapter: object)

skipFrameworkBuild​

Whether to skip the framework build and use existing build output when npx ownstak build command is called.

  • Type: boolean
  • Default: false
  • Setter: .setSkipFrameworkBuild(skip: boolean = true)

assets​

Configuration for static assets (static files that don't contain a hash in their name and can change between deployments, e.g., index.html). This option is usually configured by the frameworkAdapter. The include keys can contain files, directories, or glob patterns that are absolute or relative to the project source directory. The value defines the target destination inside the build directory. Use true to include the asset under the same path as the source, false to exclude it, or define a custom path as a string.

  • Type: object
  • Setters:
    • .includeAsset(path: string, destination?: string): Includes a static asset.
    • .setDefaultFile(filePath: string): Sets the default file to serve when no route matches.
    • .setDefaultStatus(statusCode: number): Sets the default HTTP status code for unmatched routes.

permanentAssets​

Configuration for permanent static assets (files that contain a content hash in their name and are expected to never change, e.g., chunk-asdf123.js). This option is usually configured by the frameworkAdapter. It uses the same format as assets.

  • Type: object
  • Setters:
    • .includePermanentAsset(path: string, destination?: string): Includes a permanent asset.

debugAssets​

Configuration for debug assets.

  • Type: object
  • Setters:
    • .includeDebugAsset(path: string, destination?: string): Includes a debug asset.

app​

Configuration for your application code. Use this to include additional files in your build, such as dynamically loaded dependencies.

  • Type: object
  • Setters:
    • .includeApp(path: string, destination?: string): Includes an application file.
    • .setAppEntrypoint(entrypoint: string): Sets the entry point for your application.

Methods Example​

The Config provides several methods for programmatically setting configuration values in your own code. Here's an example of all available methods:

ownstak.config.mjs
import { Config } from 'ownstak';

export default new Config()
  .setOrganization('my-org')
  .setProject('my-app')
  .setEnvironment('production')
  .setRuntime('nodejs20')
  .setMemory(2048)
  .setArch('x86_64')
  .setTimeout(30)
  .setFramework('static')
  .includeAsset('./public', './')
  .includePermanentAsset('./static')
  .includeDebugAsset('./debug')
  .includeApp('./dist/server.js', './server.js')
  .setAppEntrypoint('./server.js');
tip

This is the default and recommended way to define your OwnStak project configuration.

Options Example​

Here's a complete example showing all available options on Config object:

ownstak.config.js
import { Config } from 'ownstak';

export default new Config({
  project: 'my-nextjs-app',
  organization: 'my-org',
  environment: 'production',
  runtime: 'nodejs20',
  memory: 2048,
  arch: 'x86_64',
  timeout: 30,
  framework: 'nextjs',
  skipFrameworkBuild: false,
  assets: {
    htmlToFolders: true,
    include: {
      './public': './',
      './static': true,
      './public/*.{js,css}': false
    }
  },
  permanentAssets: {
    htmlToFolders: false,
    include: {
      './_astro': './'
    }
  },
  debugAssets: {
    include: {
      './debug': true
    }
  },
  app: {
    include: {
      './dist/server.js': './server.js'
    },
    entrypoint: './server.js'
  }
});

JSON Example​

If you prefer not to install ownstak as a project dependency or simply want to avoid using JavaScript/TypeScript, you can define the configuration using a plain JSON file:

ownstak.config.json
{
  "project": "my-nextjs-app",
  "organization": "my-org"
}
note

Environment variables cannot be used with the JSON config.