Get started with Project IDX

Read on for the basics you need to start using Project IDX.

Before you begin

Before you get started, you might need to enable third-party cookies for your browser. Project IDX requires third-party cookies in most browsers to authenticate workspaces.

Create a workspace

A workspace in IDX is a development environment that contains everything you need to develop your application. It contains your code, a code editor (with plugins relevant to your project), and toolchains that support app development. It's similar to creating a new project in your local Desktop development environment, except you have a whole computer and OS pre-configured and dedicated exclusively to building an application.

Project IDX workspaces are optimized to contain one codebase at a time, so you can keep the environments and system-level dependencies of different applications isolated from each other.

If you're building a new app, use managed workspace templates in IDX to get started quickly. Alternatively, you can import your existing application codebases into IDX.

To create a new workspace, follow these steps:

1. Open Project IDX

2. The first time you open IDX, you're prompted to read and accept the terms of service for Google products, Generative AI, and the Android SDK. You can also opt-in to communications about product updates and announcements or user studies to improve our product. Select the options that make sense for you. Click the links provided to read the terms of service, then select the option to accept them and click Continue. Next, you can decide to Enable AI Features from your first use of IDX, or leave them off by clicking Not Right Now (you can always turn them on later). If you do enable them on this screen, read the note on AI and privacy and then click Continue to keep your settings or Go Back to turn AI features off.

3. Select the type of workspace you want to create:

   • Templates: Create a workspace pre-loaded with the basic files and packages you might need. Select one of the featured templates or click See all templates for a full list of available frameworks, APIs, and languages. You can also find the Blank workspace template in the template library.
   • GitHub repository: Select Import a repo to clone a GitHub repository into your workspace.

Configure your workspace

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. Learn more about Nix + IDX.

Create or edit the .idx/dev.nix file

Environment configuration is defined in the .idx/dev.nix file in your code repository. This file lets you specify packages that are installed, environment variables, and Code OSS extensions.

See the following example .idx/dev.nix file for a basic workspace environment configuration that enables app previews in IDX:

{ 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";
      }
    ];
  };
}

Apply new configuration

Any time you add or update the dev.nix configuration file, IDX shows a prompt in the bottom-right corner to Rebuild the environment. The time it takes to rebuild the environment depends on the number of packages your configuration needs.

Debug environment build failures

Given that configuration files are machine-readable code, they can have errors. If this happens, the environment may fail to build and not start. IDX displays an option to start a Recovery environment. This workspace doesn't include any of the configuration you've defined and just runs basic Code OSS. This gives you the chance to fix errors in your dev.nix configuration file and rebuild the environment.

IDX will eventually surface environment build errors. For now, you have to troubleshoot on your own.

Next steps

• Preview your app.

• Share your workspace.