How do I run an old project?

We're going to make a couple of basic assumptions:

• You didn't create the project yourself.
• The project uses a package.json file to manage dependencies.

That said, some of the advice will still be valid even if those assumptions don't apply.

Before we start, there's one key thing to keep in mind...

⚠️ It is possible that the code you've been given never actually worked.

You'll need to assess for yourself how likely that is for the specific project you're trying to run.

It is not uncommon for lone developers to have local changes that they never check into source control. If you've cloned a repository from GitHub, then it is possible that the code just doesn't work. It might be easy to fix, it might not. This is one of the reasons why projects use automated CI tools, to ensure that the latest code can be built successfully, without needing local modifications.

It's also possible that some aspect of the project only works on a specific operating system, or a particular version of Node, or requires some other tooling to be installed on your system.

README.md

First check whether the project has a README.md. You never know your luck, the developers might have included instructions. However, you need to be careful not to trust the README.md. The instructions may well be out of date, or they could be boilerplate instructions that were automatically added to the project by a scaffolding tool, not something written by the developers.

package.json

Have a look in the package.json. Have a look through the dependencies, just to get a sense of what it uses.

Then take a look at the scripts sections. That'll tell you how to run things, both during development and for a production build. As with the README.md, you need to keep in mind that these might have been automatically generated by a tool, and there's no guarantee that the original developers actually used all of them.

Project-specific config files

Some projects have config files that you'll need to edit before you can build/run them. These are typically used for things like database settings and authentication keys. Look for files at the root of the project with names like .env.example or config.example.js, or anything else that looks like it might be a configuration file for the project.

If you're getting a build error complaining about a missing config file, then it might be because you have to create it yourself, with your local settings.

Lock files

The package versions listed in package.json are typically ranges, rather than specific versions. Historically, this meant that the local versions of the dependencies would depend on when you installed them. Not everyone would get the same versions.

The package ranges should take semantic versioning into account, so using a slightly newer version of a package shouldn't break backwards compatibility with the project. But, in practice, if a project has enough dependencies then it's quite likely that something will go wrong if the versions aren't exactly right.

This used to be a common problem. To solve it, package manager introduced an additional file, known as a lock file.

The lock file specifies the exact versions that should be installed for the dependencies.

If a project is old enough, it may predate the introduction of lock files. It's also possible that the developers didn't add the lock file to source control, either unintentionally or due to misunderstanding lock files.

Note

There is a separate and unrelated concept, also known as a 'lock file', which is used to ensure that two processes/threads don't try to do the same thing at the same time. That type of lock file should not be committed to source control. This is not the same thing as the lock file created by JavaScript package managers.

If the project you're trying to run doesn't have a lock file, that is a bad sign.

The lock file name is also the easiest way to identify which package manager the original developers were using:

Package manager	Lock file
npm	package-lock.json
yarn	yarn.lock
pnpm	pnpm-lock.yaml

Try to use the same package manager as the original developers. So rather than using npm install, use yarn install or pnpm install if that's what the project used.

Using old versions

If there's no lock file, and the project seems to need older versions, then you've got a few options.

If you can identify a date when the project worked, you can install the versions that existed before that date:

npm install --before 2020-04-21

Documentation: https://docs.npmjs.com/cli/v9/using-npm/config#before

If that still doesn't give you the versions you want, you may need to resort to editing the package.json to specify the exact versions. e.g. ^1.2.3 specifies a minimum version, whereas 1.2.3 would specify an exact version.

But always keep in mind that it is possible that the developer forgot to commit some of their changes to package.json, so it is possible that the versions you need don't match what you can see in that file.

Common failures for Vue projects

node-sass

node-sass was always tricky to install, particularly on Windows. Despite what the name suggests, it isn't a pure JavaScript implementation of Sass, and it needs various things to be installed on your machine (e.g. Python) to work correctly.

Each new release of Node needs a new release of node-sass. Chances are it won't work with whatever version of Node you're currently running.

node-sass is also deprecated.

Thankfully, this is usually easy to fix. Use your package manager to remove node-sass and install sass instead.

webpack

If you're using an older version of webpack with a new version of Node then you may see an error like this:

digital envelope routines::unsupported

Or:

digital envelope routines::initialization error

This includes Vue CLI projects, especially those on version 4.

This is caused by Node and OpenSSL trying to keep up with the latest security best practices, but older dependencies can't retrospectively comply with the new standards.

Upgrading webpack would fix the problem, but it usually isn't practical if you just want to get an old project running. You've got two alternative solutions to choose from:

• Use an older version of Node.
• Set the NODE_OPTIONS environment variable to --openssl-legacy-provider. Typically, that'll be using either SET NODE_OPTIONS=--openssl-legacy-provider or export NODE_OPTIONS=--openssl-legacy-provider, depending on your operating system.

See https://github.com/vuejs/vue-cli/issues/6770 for more discussion of the problem.