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 = {
web = {
command = [
"npm"
"run"
"start"
"--"
"--port"
"$PORT"
"--host"
"0.0.0.0"
"--disable-host-check"
];
manager = "web";
};
};
};
}
Nix attributes and package libraries
packages
Packages to install in the environment.
You can use the pkgs argument to select packages to install, for example
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, for example
${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 or path)
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 = {
web = {
command = ["yes"];
cwd = "subfolder";
manager = "web";
env = {
HELLO = "world";
};
};
};
};
}
Type: attribute set of (submodule)
Default: { }
idx.previews.previews.<name>.command
Command to execute
Type: list of string
Default: [ ]
idx.previews.previews.<name>.cwd
Working directory
Type: string
Default: ""
idx.previews.previews.<name>.env
Environment variables to set.
Type: attribute set of string
Default: { }
idx.previews.previews.<name>.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.
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.
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
services.mysql.enable
Whether to enable MySQL server.
The server is initialized with a passwordless user root. So to create additional
users and create databases use mysql -u root. .
Type: boolean
Default: false
Example: true
services.mysql.package
MySQL package to use.
Type: package
Default: pkgs.mysql
Example: pkgs.mysql80
services.postgres.enable
Whether to enable PostgreSQL server.
Type: boolean
Default: false
Example: true
services.postgres.package
PostgreSQL package to use.
Type: package
Default: pkgs.postgresql
Example: pkgs.postgresql_15
services.postgres.extensions
Postgres extensions to install.
Type: list of (one of "age", "apache_datasketches", "cstore_fdw", "hypopg", "jsonb_deep_sum", "periods", "pg_auto_failover", "pg_bigm", "pg_cron", "pg_ed25519", "pg_embedding", "pg_hint_plan", "pg_hll", "pg_ivm", "pg_net", "pg_partman", "pg_rational", "pg_relusage", "pg_repack", "pg_safeupdate", "pg_similarity", "pg_topn", "pg_uuidv7", "pgaudit", "pgjwt", "pgroonga", "pgrouting", "pgsql-http", "pgtap", "pgvector", "plpgsql_check", "plr", "plv8", "postgis", "promscale_extension", "repmgr", "rum", "smlar", "tds_fdw", "temporal_tables", "timescaledb", "timescaledb-apache", "timescaledb_toolkit", "tsearch_extras", "tsja", "wal2json")
Default: [ ]
Example: [ "pgvector" "postgis" ];
services.pubsub.enable
Whether to enable Google Pub/Sub emulator.
More documentation on using the emulator can be found here: https://cloud.google.com/pubsub/docs/emulator#using_the_emulator .
Type: boolean
Default: false
Example: true
services.pubsub.port
Configures the port Pub/Sub will listen on.
Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)
Default: 8085
services.pubsub.project-id
Project ID to use to run the Pub/Sub emulator. This project is for testing only, it does not have to exist and is only used locally.
Type: string matching the pattern [a-z][a-z0-9-]{5,29}
Default: "idx-pubsub-emulator"
services.redis.enable
Whether to enable Redis server.
Type: boolean
Default: false
Example: true
services.redis.port
Configures the port Redis will listen on.
By default tcp is disabled and redis only listens on /tmp/redis/redis.sock.
Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)
Default: 0
services.spanner.enable
Whether to enable Google Cloud Spanner Emulator.
Type: boolean
Default: false
Example: true
services.spanner.fault-injection
Whether to enable random fault injection into transations.
Type: boolean
Default: false
Example: true
services.spanner.grpc-port
The TCP port to which the emulator should be bound.
Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)
Default: 9010
services.spanner.rest-port
The port at which REST requests are served
Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)
Default: 9020