Running Intro to AI Engineering locally

Use this page to run the extracted Gift Genie project on your computer. The current course has two forms of the project: a browser-only Vite app and, after the backend migration, an Express and Vite app. Identify the form you have, then follow its setup below.

What you need first

Install a supported LTS version of Node.js. Node 24 is recommended. Node 22.12 or later also supports the Vite version used by the course's later projects.

Check that Node and npm are available:

$ node --version
v24.18.0
$ npm --version
11.18.0

npm is included with Node. If either command says "command not found", finish installing Node before continuing.

JunoWhat you need first Install the LTS version of Node.js. It includes npm, so one download gives you both tools. If both version commands print a number, your machine is ready.

JunoWhat you need first Use Node 24, or Node 22.12 and later. That covers the runtime the Vite 7 projects near the end of the course expect, so you set it up once for the whole course.

JunoWhat you need first The later projects use Vite 7.3. Its minimum is Node 20.19 or 22.12, but Node 20 has reached end of life, so in practice that means Node 22.12 or newer. Install a currently supported LTS rather than the oldest release that meets the minimum.

Identify the project you extracted

Move into the extracted folder containing package.json:

$ cd path-to-your-downloaded-project

All commands on this page run from that folder.

Then check which form of the project you have. The browser-only version has index.html and vite.config.js, and its start script runs no server file. The Express and Vite version has both server.js and vite.config.js, and its start script runs them together.

JunoIdentify the project you extracted Open a terminal in the folder with package.json and read its start script. If it runs a server.js file, follow the backend section. If it does not, you have the browser-only version.

JunoIdentify the project you extracted The start script in package.json tells you what actually runs. A Vite-only lesson and the later Express-plus-Vite app need different setup below, so settle which one you have before you install anything.

JunoIdentify the project you extracted When the extracted scripts or lockfile differ from an example here, follow the files. They decide which processes start and which install command applies to your lesson.

Add your environment values

Scrimba supplies three environment variables from your account settings. Your computer does not have access to those settings, so create a file named .env beside package.json:

AI_URL=https://your-provider.example/v1
AI_KEY=your-key-here
AI_MODEL=your-model-id

Copy the values you used in the course. The URL and model must belong to the same provider as the key.

Before using Git, create a .gitignore file beside package.json and add:

.env
node_modules/

The Git handbook explains why these two lines belong in every project in ignoring files and good habits.

Never commit your API key

The .env file contains a working credential. Do not upload it, paste it into source code, or commit it to Git. If a key is exposed, revoke it at the provider and create a new one.

Restart the project after any change to .env. The correct run command depends on which part of the course the ZIP came from.

JunoAdd your environment values Create .env right beside package.json and copy your three Scrimba values into it. They are the same values Scrimba kept in your account settings, now stored on your own computer. Keep that file out of Git.

JunoAdd your environment values The course reads AI_URL, AI_KEY, and AI_MODEL as a set so one client can point at different OpenAI-compatible providers. Restart after changing any of them, because a running process keeps the old values.

JunoAdd your environment values The browser-only projects load .env in the Vite config and write the values into the client bundle. In the backend download, nothing loads the file for Node until you make the one package-script change covered below.

Run the browser-only Gift Genie

Gift Genie lessons before the backend migration have index.html and vite.config.js, but no active server.js in the start script. Install and start the project:

$ npm install
$ npm start

Vite prints a local address similar to this:

  VITE ready

  Local: http://localhost:5173/

Open the exact Local URL printed in your terminal. If port 5173 is busy, Vite normally selects another port and prints that address instead. Stop Vite with Ctrl+C.

This version exposes your key to the browser

These lessons deliberately call the AI provider from frontend JavaScript. Vite copies AI_KEY into the browser bundle, so anyone who opens the page can read the key in their browser's developer tools. Use a temporary, restricted key for local learning. Do not deploy this version or share it on a network. The backend migration later in the course is the secure architecture to build on.

JunoRun the browser-only Gift Genie Run npm install, then npm start, and open the exact Local URL Vite prints rather than one you remember. Press Ctrl+C when you finish.

JunoRun the browser-only Gift Genie This project is Vite-only even when an unused server file sits in the folder. The start script decides what actually runs, so trust it over the file listing.

JunoRun the browser-only Gift Genie The downloaded Vite config uses define to replace process.env.AI_KEY, AI_URL, and AI_MODEL at build time, so the key reaches every browser that loads the page. Use a restricted throwaway key and treat it as already public.

Run the Gift Genie with its backend

The backend migration and later lessons have both server.js and vite.config.js. Their start script launches Express and Vite together. The current download does not load .env into the Express process automatically, so make this one change in package.json before starting it.

Find the server script:

"server": "node --watch server.js"

Change it to:

"server": "node --env-file=.env --watch server.js"

The Deployment module's project needs the same --env-file change for its server.

Add the backend port to .env:

AI_URL=https://your-provider.example/v1
AI_KEY=your-key-here
AI_MODEL=your-model-id
PORT=3001

Then install and start both processes:

$ npm install
$ npm start

You should see an Express message for port 3001 and a Vite Local URL, usually port 5173. Open the Vite URL. Do not open port 3001 as the application page. The browser sends /api requests to Vite, and Vite proxies them to Express. The API key stays in the server process.

Stop both processes with Ctrl+C.

Keep the backend on port 3001

The downloaded Express server reads PORT, but its Vite proxy points directly to http://localhost:3001. Leave PORT=3001 unless another process needs that port. If you change it, also change the proxy target in vite.config.js to the same port and restart the project.

JunoRun the Gift Genie with its backend Keep PORT=3001, run npm install and npm start, then open the Vite URL, not port 3001. One Ctrl+C stops both parts of the app.

JunoRun the Gift Genie with its backend One command starts Express on port 3001 and Vite on its printed frontend port. Open the Vite URL: it forwards relative /api requests to Express, which is how the key stays on the server.

JunoRun the Gift Genie with its backend The start script uses the concurrently package to run Node and Vite as one command. The added --env-file=.env flag loads credentials only in the Express process, while the Vite config owns the fixed development proxy target.

Troubleshooting

Missing AI_KEY, a 401 response, or an authentication error: Check the spelling of all three variable names, confirm the key is active, and restart the project. A key, URL, and model from different providers will not work as a set.

The model cannot be found or the provider rejects the request: Copy the model ID exactly. Some course features, including Responses API tools, the built-in helpers a model can call during a request, are not supported by every OpenAI-compatible provider, or by every model those providers offer.

npm start says a package or command is missing: Make sure the terminal is in the folder containing package.json, then run npm install again. If the download contains a lockfile for a different package manager, follow that lockfile instead of generating a second one.

The page opens, but an /api request fails: This applies to the backend version. Check that both Express and Vite are still running in the same terminal. Confirm Express is on port 3001 and the proxy target in vite.config.js also says 3001.

EADDRINUSE mentions port 3001: Another process is using the backend port. Stop that process, or change both PORT in .env and the Vite proxy target to the same unused port.

Vite uses 5174 or another frontend port: That is normal when 5173 is busy. Open the Local URL Vite printed. You do not need to change the Express port.

JunoTroubleshooting Check that your terminal is in the folder with package.json, that .env holds all three AI values, and that you restarted after editing it. For the backend version, keep both processes running.

JunoTroubleshooting Separate environment failures from process failures. A 401 points at provider configuration; a failed /api request usually means Express stopped or the proxy port does not match. Name the category first and the specific error gets easier to read.

JunoTroubleshooting Read the downloaded package.json before changing any command. The start script says whether Vite runs alone or beside Express, and the lockfile says this download expects npm.