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, which includes npm, so one download gives you both tools. If both version commands print numbers, your machine is ready to go.

JunoWhat you need first Grab 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 and stop thinking about it.

JunoWhat you need first The later projects use Vite 7.3, which needs Node 20.19 or Node 22.12 and later. Install a currently supported LTS rather than the oldest release that still meets the minimum; I have chased too many runtime bugs that began with a version chosen that way.

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 Check one thing before you pick a section: if the start script runs a server.js file, follow the backend section, and if it does not, you have the browser-only version. I once spent an afternoon on the wrong instructions because I skipped this check!

JunoIdentify the project you extracted Open package.json and read the start script; it tells you what actually runs. A Vite-only lesson and the later Express-plus-Vite app use different instructions below, so decide which form you have before you start, or you will follow the wrong section and have to begin again.

JunoIdentify the project you extracted When the extracted scripts or lockfile differ from an example here, follow the files. They determine which processes start and which install command applies, and I have learned to trust a lockfile over my memory of any 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. Those are the same values Scrimba held in your account settings, now stored on your own computer instead. Keep that file out of Git; leaking a key is a mistake I made early so you do not have to.

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. Change any of them and restart; the running process keeps the old values otherwise.

JunoAdd your environment values The browser-only projects load .env in Vite config and write the values into the client bundle at build time. The current backend download needs one package-script change before Node loads the same file, covered below; nothing loads it for you, a fact I rediscover on every fresh machine.

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. Ctrl+C stops it when you finish; that habit took me longer to learn than I care to admit.

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

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

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 course 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, which felt like magic the first time I saw it.

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 server-side.

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. That is tidier than starting two terminals by hand, which I still catch myself doing from old habit.

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, and they are not supported 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. Nearly every error I saw early on came from one of those three things.

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. Identify the category first, and the specific error becomes clear.

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. Reading it takes five seconds and prevents the debugging session I would otherwise spend an hour on.