The goal of Project IDX is to be as useful to developers as possible. One way IDX accomplishes this is to give developers the freedom and flexibility to install the right tools for any given project on their workspace and customize settings so their workspaces work for them.
Nix + IDX
IDX uses Nix to define the environment configuration for each workspace. Nix is a purely functional package manager and assigns unique identifiers to each dependency, which ultimately means your environment can contain multiple versions of the same dependency, seamlessly. It is also reproducible and declarative. In the context of IDX, this means you can share your Nix configuration file across workspaces to load the same environment configuration.
IDX defines the preview environment and workspace package configurations
directly from the code repository with the .idx/dev.nix file.
The attributes and package libraries you can define in this file follow the
Nix attribute set syntax.
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 = [
{
command = [
"npm"
"run"
"start"
"--"
"--port"
"$PORT"
"--host"
"0.0.0.0"
"--disable-host-check"
];
manager = "web";
id = "web";
}
];
};
}
Nix attributes and package libraries
packages
Packages to install in the environment.
You can use the pkgs argument to select packages to install, i.e. pkgs.python3.
Note that the contents of pkgs depends on the selected channel channel option.
Example:
{pkgs, ...}: {
channel = "stable-23.11";
packages = [pkgs.vim];
}
You can search for available packages here: stable-23.11 or unstable.
Type: list of package
Default:
[ ]
channel
nixpkgs channel to use.
This channel defines the contents of the pkgs argument.
Type: one of “stable-23.05”, “stable-23.11”, “unstable”
Default:
"stable-23.11"
env
Environment variables that are set inside the developer environment.
These are propagated to all of your shells and the preview server. Environment variables can be especially useful if your application requires a specific set of variables.
Example:
{pkgs, ...}: {
env = {
HELLO = "world";
};
}
Type: attribute set of anything
Default:
{ }
idx.extensions
Code extensions you want to install in your IDX workspace.
This is a list of fully qualified extension ids, i.e. ${publisherId}.${extensionId}.
You can find a list of available extensions on the Open VSX Registry
and enter them in your dev.nix file by ${publisherId}.${extensionId}.
Type: list of non-empty string
Default:
[ ]
idx.previews.enable
Set this to true to enable IDX Previews.
This feature provides a way to run and reload your apps automatically as you are developing them.
Type: boolean
Default:
true
Example:
true
idx.previews.previews
Preview configurations.
Define the commands IDX executes in your developer environment.
Example:
{pkgs, ...}: {
idx.previews = {
enable = true;
previews = [
{
command = ["yes"];
cwd = "subfolder";
manager = "web";
id = "web";
env = {
HELLO = "world";
};
}
];
};
}
Type: list of (submodule)
Default:
[ ]
idx.previews.previews.*.command
Command to execute
Type: list of string
Default:
[ ]
idx.previews.previews.*.cwd
Working directory
Type: string
Default:
""
idx.previews.previews.*.env
Environment variables to set.
Type: attribute set of string
Default:
{ }
idx.previews.previews.*.id
ID for the preview
Type: non-empty string
idx.previews.previews.*.manager
Manager
Type:
one of web, flutter
idx.workspace.onCreate
Commands to execute when the workspace is created and opened for the first time.
This can be useful to setup the development environment. For example, here we are
specifying npm install to run:
{pkgs, ...}: {
idx.workspace.onCreate = {
npm-install = "npm install";
};
}
Type: attribute set of (path or string)
Default:
{ }
idx.workspace.onStart
Commands to execute whenever the workspace is opened.
This can be useful to start build watchers. For example, here we are specifying 2 commands to run:
{pkgs, ...}: {
idx.workspace.onStart = {
npm-watch-fe = "npm run watch:frontend";
npm-watch-be = "npm run watch:backend";
};
}
Type: attribute set of (path or string)
Default:
{ }
services.docker.enable
Whether to enable Rootless docker.
Type: boolean
Default:
false
Example:
true