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.

Chrome

1. Open Settings.
2. Open the Privacy and Security tab.
3. Make sure Allow all cookies is enabled.
4. Open idx.google.com.
5. Click the visibility icon in the address bar visibility_off to open the Tracking Protection panel. Turn on the Third-party cookies setting to temporarily allow third-party cookies. This enables cookies on IDX for 90 days.

Safari

1. Open Safari > Settings....
2. Turn off the following settings:
   • Advanced > Block all cookies
   • Privacy > Prevent cross-site tracking
3. Open idx.google.com.

Firefox

You don't need to enable third-party cookies for Firefox. Go to idx.google.com.

Opera

1. Open idx.google.com.
2. Open the menu and click Settings.
3. Go to the Privacy & Security section and expand the Third-party cookies option.
4. Select Block third-party cookies in Incognito mode or Allow third-party cookies.
5. Open idx.google.com.

Arc

1. Go to arc://settings.
2. Go to the Privacy and security section and expand the Third-party cookies option.
3. Select Block third-party cookies in Incognito mode or Allow third-party cookies.
4. Open idx.google.com.

Brave

You don't need to enable third-party cookies for Brave. Go to idx.google.com.

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.

Key Point: There's a limit to how many workspaces you can create. If you have a Google Developer Profile, you can create up to 5 workspaces. To create a Google Developer Profile directly from IDX once you've hit the workspace limit, click Complete Setup from the notification on the template dashboard.

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.
   • Git Repository: Select Import a repo to clone a repository into your workspace.

Templates

1. Browse templates by application type or use the search box in the upper-right to filter the full template library by keyword. The Blank workspace template is available in the Misc category.

2. Enter a name for your workspace and set any additional options.

3. Click Create. IDX creates a new workspace based on your selections.

We're always adding new templates, so keep checking back or tell us what you want to see.

Git Repository import

1. Enter the Repo URL. The repository can be hosted on GitHub, GitLab or Bitbucket.

2. Click Create. IDX creates a new workspace based on your selections.

3. For private repositories, you will be asked to authenticate to the respective provider.

   • For GitHub, follow the prompts to copy an access token
   • For GitLab, you can use your account password or create a personal account token
   • For Bitbucket, use your username (not email) and an app password to authenticate.

4. Run npm install (or flutter pub get) in the IDX terminal after importing your project. By default, IDX doesn't install npm dependencies when you import a project.

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 = {
      web = {
        command = [
          "npm"
          "run"
          "start"
          "--"
          "--port"
          "$PORT"
          "--host"
          "0.0.0.0"
          "--disable-host-check"
        ];
        manager = "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.