Customize your IDX workspace

Project IDX lets you to tailor your workspace to your project's unique needs by defining a single .idx/dev.nix configuration file that describes:

  • The system tools that you need to be able to run (for example, from the Terminal), such as compilers or other binaries.
  • The IDE extensions you need installed (for example, programming language support).
  • How your app previews should show up (for example, the commands to run your web server).
  • Global environment variables available to local servers running in your workspace.

See the dev.nix reference for a complete description of what's available.

Nix and IDX

IDX uses Nix to define the environment configuration for each workspace. Specifically, IDX uses:

  • The Nix programming language to describe workspace environments. Nix is a functional programming language. The attributes and package libraries you can define in the dev.nix file follow the Nix attribute set syntax.

  • The Nix package manager to manage the system tools available to your workspace. This is similar to OS-specific package managers such as APT (apt and apt-get), Homebrew (brew), and dpkg.

Because Nix environments are reproducible and declarative, in the context of IDX, this means you can share your Nix configuration file as part of your Git repository to ensure everyone who works on your project has the same environment configuration.

A basic example

The following example shows a basic environment configuration enabling previews:

{ pkgs, ... }: {

  # Which nixpkgs channel to use.
  channel = "stable-23.11"; # or "unstable"

  # Use https://search.nixos.org/packages to find packages
  packages = [
    pkgs.nodejs_18
  ];

  # Sets environment variables in the workspace
  env = {
    SOME_ENV_VAR = "hello";
  };

  # Search for the extensions you want on https://open-vsx.org/ and use "publisher.id"
  idx.extensions = [
    "angular.ng-template"
  ];

  # Enable previews and customize configuration
  idx.previews = {
    enable = true;
    previews = {
      web = {
        command = [
          "npm"
          "run"
          "start"
          "--"
          "--port"
          "$PORT"
          "--host"
          "0.0.0.0"
          "--disable-host-check"
        ];
        manager = "web";
        # Optionally, specify a directory that contains your web app
        # cwd = "app/client";
      };
    };
  };
}

Add system tools

To add system tools to your workspace, such as compilers or CLI programs for cloud services, find the unique package ID in the Nix package registry and add it to your dev.nix file's packages object, prefixed with `pkgs.:

{ pkgs, ... }: {
  # Which nixpkgs channel to use.
  channel = "stable-23.11"; # or "unstable"

  # Use https://search.nixos.org/packages to find packages
  packages = [
    pkgs.nodejs_18
  ];
  ...
}

This is different from how you might typically install system packages using OS-specific package managers such as APT (apt and apt-get), Homebrew (brew), and dpkg. Declaratively describing exactly which system packages are needed means IDX workspaces are easier to share and reproduce.

Use local node binaries

Just like on your local machine, binaries related to locally installed node packages (i.e. packages defined in your package.json) can be executed in a Terminal panel by invoking them with the npx command.

As an additional convenience, if you're in a directory with a node_modules folder (such as the root directory of a web project), locally installed binaries can be invoked directly, without the npx prefix.

Add gcloud components

A default configuration of the gcloud CLI for Google Cloud is available to all IDX workspaces.

If you need additional components, you can add them to your dev.nix file like so:

{ pkgs }: {
  packages = [
    ...
    (pkgs.google-cloud-sdk.withExtraComponents [
      pkgs.google-cloud-sdk.components.cloud-datastore-emulator
    ])
    ...
  ];
}

Add IDE extensions

You can install extensions in IDX using the OpenVSX extension registry in two ways:

  • By using the Extensions panel in IDX to discover and install extensions. This approach is best for user-specific extensions, such as:

    • Custom color themes

  • By adding extensions to your dev.nix file. These extensions will be automatically installed when you share your workspace configuration. This approach is best for project-specific extensions, such as:

    • Programming language extensions, including language-specific debuggers
    • Official extensions for cloud services used in your project
    • Code formatters

For the latter approach, you can include IDE extensions in your dev.nix file by finding the fully-qualified extension ID (of the form <publisher>.<id>) and adding it to the idx.extensions object like so:

{ pkgs, ... }: {
  ...
  # Search for the extensions you want on https://open-vsx.org/ and use the format
  # "<publisher>.<id>"
  idx.extensions = [
    "angular.ng-template"
  ];
  ...
}

Add common services

IDX also offers simplified setup and configuration for common services you may need during development, including:

  • Containers
    • Docker (services.docker.*)
  • Messaging
    • Pub/Sub Emulator (services.pubsub.*)
  • Databases
    • MySQL (services.mysql.*)
    • Postgres (services.postgres.*)
    • Redis (services.redis.*)
    • Spanner (services.spanner.*)

For details on enabling these services in your workspace, see the services.* portions of the dev.nix reference.

Customize previews

For details on how to customize your app previews, see the documentation for previews.

Set your workspace icon

You can choose a custom icon for your workspace, by placing a PNG file named icon.png next to the dev.nix file, inside the .idx directory. IDX will then use this icon to represent your workspace in your dashboard.

Because this file can be checked into source control (such as Git), this is a good way to help everyone who works on your project see the same icon for your project when using IDX. And because the file can vary across Git branches, you can even visually distinguish workspaces when working on "beta" and "production" releases of your app, for example.

Turn your customizations into a template

To turn your environment configuration into a "starter environment" for anyone to build new projects with, see the docs for creating a custom template.

See all customization options

See the dev.nix reference for a detailed description of the environment configuration schema.