Installing an Existing npm Project

Most of the time you won't be assembling a project from scratch. You'll be cloning or downloading an existing npm project, and the faster route is to let npm install all of the individual pieces for you. For the remainder of this guide, we'll walk through doing exactly that, using a real-life project of mine as the example.

The first step is simple. Where to start with existing npm projects — like my real-life one, is to run npm install while in the project's root directory. The project's dependencies are downloaded and installed to node_modules in no time at all.

That said, depending on the particular project you're setting up, there are a few things that you might run into.

The first thing is the need to install an npm package ad hoc. This command will use npm install to install package lodash into the project folder.

Be careful with the way you've named your projects, too. Note the use of the underscore naming

We've also mentioned earlier that you need a .gitignore file to properly specify the files you don't want committed to the Git repository for your project. The node_modules of an existing project probably isn't going to be committed for that reason.

What to do if we find that known package names around the world used as project dependency names later on work correctly, and don't break stuff we've installed other directories above them?

  • npm install will hit the errors if there's:
  • version mismatch issues
  • npm version
  • OS mismatch

'package-lock.json' and 'npm-shrinkwrap.json' are the two commands through which we can resolve conflicts that arise in the versions when developing.

We'll have to create and install the packages fresh since we don't necessarily have access to their own version in this new folder. Since these dependencies will follow their own naming conventions, and different package managers will differ in this regard, one thing's sure. Among other challenges that npm projects face are malformed JSON like package.json, unsupported syntax, and an inadequate registry reachability while installing dependencies, which can prevent you from installing dependencies at all. One example mentioned by the docs is when running an npm installation on a system nowhere near the supported versions, which will crash the process entirely.

We can only install dependencies for projects we own or maintain, and should be aware that some private or unpublished packages the project can't access newer available versions. Please don't abuse this ability, only doing what's necessary in order to get our project to run.

One last note is important to know if we want to install existing projects that are (mostly) undocumented and written by other people: private packages are behind login-protected registries or must be accessed by credentials. We'll have to have the project maintainer's permission and registry authentication credentials to install them.

Similarly, there are a whole slew of things that are likely to keep us from actually installing, building or testing versions past a given point. Often, we are simply only looking for a clean bootstrap able to run the project, not the original intended installation process whatsoever. However, the assumption going in is that the original code's integrity has not been violated, so the given command should never result in removing dependencies that have been installed this way as conflicts could arise during the develop.

Putting an existing npm project on your machine

To walk through this end to end, the guide uses the SvelteKit static blog starter — a real project with a generous set of pre-installed packages, which makes it useful for demonstration. Its purpose is to give a head-start on a statically generated blog, meaning the code compiles down to .html files ready to deploy anywhere, one of the approaches under the Jamstack umbrella. No prior SvelteKit knowledge is required. Worth noting: SvelteKit runs on Vite underneath, itself an npm package that supplies modern build tooling and a fast development server.

Two ways to clone

“Cloning” just means copying the project to your system so you can work on it locally, and there are two routes.

  • In the browser: go to the starter repo on GitHub, open the “Code” dropdown in the GitHub UI, and pick “Download ZIP.”
A screenshot of a GitHub repo zoomed in to the top-right corner of the page with the Code button clicked and showing options to clone the repository. The option to download a ZIP file has a big white arrow pointing at it towards the left to call it out for this existing npm project.
  • On the command line: make sure you're somewhere you don't mind a new project folder appearing (e.g. cd /path/to/folder), then run:
npx degit https://github.com/josh-collinsworth/sveltekit-blog-starter.git sveltekit-blog-starter

The command relies on npx, which runs npm packages without installing them permanently. degit behaves like git clone minus the Git history — “de-git.”

Either route leaves you with a fresh sveltekit-blog-starter folder. Open it in a code editor, bring up the terminal, and run npm install (or npm i).

An open dark Terminal that has run the npm i command to install an existing npm project called sveltekit-blocg-starter. 202 npm packages are installed in three seconds. There are zero vulnerabilities.
npm automatically runs an audit when installing packages.

A vulnerability note will appear, as discussed in the previous chapter — possibly “found 0 vulnerabilities” as in the screenshot, possibly more. Ignore it here; this isn't a project headed for production. The npm audit section of the earlier chapter covers the details.

Running the dev server

The package.json inside the cloned project holds the command that starts the dev server:

npm run dev

Run it and output should appear almost immediately:

An open dark terminal window that ran the npm run dev command. The terminal output shows that a localhost address has been set up where the development for the project can be previewed.

In VS Code, CMD-click the http://localhost:3000 URL, or type it into the browser manually; the site appears either way.

A screenshot of a website that is open at a localhost URL, demonstrating that the development server for the npm project is running and can be viewed in the browser. The site has a light aqua header with a My Awesome Blog heading followed by three navigation links, all centered in the container. After that is the main body of the page with a faint pale green background and darker text, including a heading that says SvelteKit static blog starter followed by a short description of the project and an unordered list of features.

SvelteKit needs Node 14 or higher. Anyone who installed npm while following this guide is fine, but if npm was already on the machine before and the project throws errors, check with node -v; nvm is the tool for upgrading. Beyond that, the project's internals aren't the point here — what matters is that a whole project is now running locally from a couple of commands, and the same procedure applies to any existing project.

Editing the project and watching it reload

The starter has several things pre-wired, which makes it easy to see the feedback loop in action.

Sass compiled on save

The Sass files live in src/lib/assets/scss/. Open global.scss, change something, and save: the browser updates near-instantly.

An animated GIF showing the development site preview open on the left and the VS Code editor on the write with a global.scss file open. The body font size is changed in the Sass code, then saved, which triggers an immediate new preview in the browser without having to manually reload the page.

Markdown as the homepage

The homepage is literally the repo's README.md. Edit that file — any edit will do, no Markdown knowledge needed — and the change shows up on save, same as with Sass:

Editing a page file such as src/routes/contact.svelte works the same way: change the HTML, save, watch it refresh live. To go further, copy one of the Markdown files in src/lib/posts/ and edit it — the new entry appears automatically in the post list on the /blog page, provided the title is unique.

How imports actually work

One npm concept was only touched on in the fourth chapter: imports, i.e. pulling a package into your code and using it right there. Open svelte.config.js in the project root and the top of the file holds a set of import lines:

import adapter from '@sveltejs/adapter-static'
import { mdsvex } from 'mdsvex'
import preprocess from 'svelte-preprocess'
import rehypeAutolinkHeadings from 'rehype-autolink-headings'
import rehypeSlug from 'rehype-slug'

Each of those imports is an installed package consumed by that file. What the packages do is beside the point; focus on the syntax, which is how packages get used inside code files: it states what to import and where from, and then the code can call it.

The style is known as “ES6 imports,” the standard that both browser JavaScript and Node JavaScript have agreed to move forward with. Node previously went its own way with a syntax called CommonJS, which it often still uses; an import in the old style looks like this:

const myPackage = require('package-name')

Here's the part that trips people up: this import syntax is an npm convention, not a language standard. Normal JavaScript does allow import — exporting a function, object or variable from one file and importing it into another is ordinary language behavior — but that requires a relative path, or in newer browsers a URL, pointing at the thing being imported. A bare package slug as a string isn't valid on its own.

It works anyway because resolving that form is one of npm's jobs. When code says import somePackage from 'name' without a path, npm searches the project's installed packages for the requested import, sparing you from typing relative paths and from knowing where anything sits inside node_modules. And since the syntax isn't valid natively, a bundler or compiler of some kind must be part of the project to turn those imports and modules into browser-ready code.

From development server to deployable files

Projects like this normally serve two purposes: developing the site or app, and producing a finalized production build. SvelteKit is no different. Once you're happy with your changes, run:

npm run build

If the dev server is still running, either stop it with Ctrl+C or open a fresh terminal tab — a terminal occupied by a continuous task won't accept new commands.

The build command works through every project file and, quite quickly, emits a bundled collection of static HTML, CSS and JavaScript ready to deploy wherever you can host a website. A build folder appears at the root of the project. Inside it, nothing browser-unreadable remains: no .md, no .svelte, just compiled HTML, CSS and JavaScript, with the CSS and JS thoroughly minified so it loads as fast as possible. Modern tooling, old-fashioned output.

Optionally, npm run preview serves the compiled result so you can see how the built site loads — content coming from the final build folder rather than compiled on the fly as the dev command does. Visually nothing differs (check the DevTools Network tab, or try editing something); you're simply looking at the final product. It's a good way to see how few compiled files come out of all those input files, and how small the bundle is — all thanks to SvelteKit and Vite.

When it comes to shipping, running build by hand and uploading the output remains an option, but a host such as Netlify or Vercel can connect to the project's GitHub repo directly and run the build command on every push to the main branch, deploying the compiled files automatically — no FTP, no dragging files around.

Working with someone else's codebase usually means pulling its dependencies down first. Cloning a repository gets you the files, but the packages the project relies on live elsewhere. The standard route is npm install, run from inside the project directory: npm reads the dependency declarations and fetches everything required to get it running.

Before you start

  • An npm installation (and therefore Node.js) on your machine. If either is missing, take care of that first — see the earlier chapter on installing npm.
  • A copy of the project directory, typically obtained by cloning its repository.

Reading the install output

Once the command finishes, don't just check for errors and move on. npm prints a summary in the terminal, and two lines in it are worth your attention:

  • Added packages: the count of packages that were actually pulled down.
  • Audited packages: the count of packages npm inspected as part of its security check, together with how many were found to contain known vulnerabilities.

After a successful install

An install that completes gives you a runnable project — you can now start it or execute its scripts. That is the whole job; there is no separate configuration step required just to get the dependencies in place.

The audit findings are informational by default: a successful install may still report vulnerable packages, and dealing with them (or not) is a separate concern from getting the project to run. Keep that distinction in mind when a fresh clone reports a handful of warnings — the install itself still did what you asked.

Context: the guide index

This chapter is the last in a nine-part series:

  1. Who the guide is for
  2. What "npm" means
  3. The command line
  4. Node and how it works with npm
  5. What a package manager is
  6. Installing npm (with Node and nvm)
  7. Installing npm packages
  8. npm commands
  9. Installing an existing npm project (this chapter)