Building from source code
To build from source you have two choices.
1) Automatic (mostly):
- Start a powershell
Invoke-WebRequest "https://raw.githubusercontent.com/Nexus-Mods/Vortex/master/bootstrap.ps1" -OutFile bootstrap.ps1to fetch the bootstrap script
- By default this script will build Vortex in "c:\build\vortex", if you want it somewhere else, edit the script to change the build directory before running it!
- You will more than likely need to allow scripts to be run. This can be set using
Set-ExecutionPolicy Unrestrictedbut a powershell with admin access is required.
- Run the script (
- This script will try to download and install all dependencies, then check out and build vortex
- Most dependencies are installed using scoop (https://scoop.sh)
- Before you can build vortex you need to download and install a couple of dependencies. If any of the download links is no longer valid, try google or a search engine of your choice.
- Download installer from nodejs.org and run the installer
- Version should not matter, the latest LTS version should be fine
- Verify that Node has installed successfully by running
node --versionin your cmd or terminal
npm install --global yarn
- Verify that Yarn has installed successfully by running
yarn --versionin your cmd or terminal
- Download installer (64-bit) from git-scm.com and run installer
- Verify that Git has installed successfully byb running
git --versionin your cmd or terminal
- Required for one of the build tools (node-gyp).
- At the time of writing versions 3.7-3.10 are known to work, 3.11 is known to not work as it has a breaking change that breaks node-gyp as of 9.3.1
- Download installer (64-bit) from python.org and run installer
- Make sure to have it added to
PATH, otherwise defaults are fine.
- If you have trouble refer to How to add Python to PATH variable in Windows
- You can disable samples and documentation if you want
- Required for some of the native builds, All versions that are even remotely recent should work
- Download installer (x64) from cmake.org and run installer
- Enable the option to add to
PATH(for the current user or all users)
Visual c++ build tools 2022 or Visual Studio 2022 (Community Edition)
- Download installer from visualstudio.microsoft.com
- You may have to google around for this as Microsoft tends to change their sitemap all the bloody time
- Under "Workloads", enable "Desktop Development with C++"
- Under "Individual Components", enable ".NET 6.0 Runtime (LTS)", ".NET SDK", "C++ ATL for latest vXYZ build tools" and "Windows 1x SDK" (any version should be fine)
Set up yarn to use C++ build tools
yarn config set msvs_version 2022 --global
- This sets up yarn to use the c++ build tools we just installed, you probably only need to do this if you've also installed other versions of Visual Studio. Can't hurt though
Cloning and building the Vortex source code
- Start a new command line prompt at this point to ensure you're using the updated PATH environment.
- Create and
cdto an appropriate directory (i.e. c:\projects)
git clone https://github.com/Nexus-Mods/Vortex.gitfrom the created directory
- this should create a new directory vortex in the current working directory (i.e. c:\projects\vortex)
- cd into the vortex directory
- Switch to an appropriate branch, if necessary
git checkout some_branch
- For development
yarn installto install dependencies
yarn buildto build
yarn startto run
- For production
- The scripts (electron-builder-oneclick.json and electron-builder-advanced.json) are set up to require code signing with a certificate you don't have so change that
yarn distto build (this will take a while)
- Find the installer and an already unpacked version in dist
If something goes wrong
If the install step fails with an error mentioning c++ or node-gyp or cmake, this will usually mean that one of the tools (python, cmake, visual studio build tools) were not installed (correctly) or can't be found, please repeat the corresponding step above and double check you followed the instructions. Then repeat the "yarn install" step. Unfortunately, with these tools being installed system-wide, it's also possible that your existing installs of other versions of these tools (visual studio build tools in particular) may interfere. We can only really promise this build works on a clean windows.
There is one component, fomod-installer, written in c# and at the time of writing its build will randomly fail for no reason. In this case you don't have to do anything special, just repeat the install step.
The automatic variant will skip dependency download and install if the download was installed previously. If a dependency install failed for some reason or you cancelled it, you will have to manually install that package (see the downloads directory).
Running the dev build
After building a dev build you can run it using
You can repeat the steps to install dependencies (
yarn install) and the full build (
yarn build) as necessary.
To save yourself time, you can rebuild just the bundled extensions (
yarn run subprojects). If you're making changes to the core application you can run build in watch mode (
yarn run buildwatch) which will be the same as yarn build but then will continue to watch for changes (only on the core application, not extensions!) and rebuild on demand.
The following section aims to clarify and explain a few development decisions.
development vs release builds
The toolchain for development builds and release builds is quite different.
In dev builds the typescript compiler (tsc) is used directly to transliterate each ts file to js individually, electron runs those files directly, dependencies are loaded from node_modules.
As a result, dev builds are easier to work with and building is much quicker but runtime is substantially.
Further, we use a two-package structure, meaning the /package.json file is used for all development and the build environment for releases (e.g. this file always controls the electron version being used/bundled) whereas /app/package.json decides settings (name, version, dependencies) for the release builds only. We use a custom script (checkPackages.js) to ensure that the dependencies for release are a subset of the build env dependencies and that they use the same version to avoid problems that didn't occur during testing because of differing dependencies.
Bundled extensions on the other hand are built the same between dev and release: they are always built with webpack and each have their own build setup - with the exception of simple game extensions which are already single js files, those simply get copied over.
yarn 1 vs yarn 3 vs npm vs pnpm
This codebase still use yarn 1 (classic). Any attempt to use yarn 2 or 3 ended up with nonsensical errors (missing dependencies that are clearly listed, successive installs leading to missing packages) with no reasonable way to investigate why. npm and pnpm are quite slow in comparison. We don't really use any yarn-specific features (workspaces?) so switching shouldn't be too difficult but for now yarn "classic" works.
esm vs commonjs
At the time of writing, electron doesn't support ES modules so everything is transpiled to commonjs. This has the consequence that some updated libraries supporting only esm can't be used (e.g. new versions of d3).
It also means that asynchronous imports (
const foo = await import('bar')) are actually synchronous at runtime. Doesn't really matter though since everything is baked into a single file on release builds anyway and code splitting isn't really needed.
- see structure.md for an overview of how the project is organized
- see https://nexus-mods.github.io/vortex-api for a description of the extension api
- see https://wiki.nexusmods.com/index.php/Vortex for usage information
Please report issues to the issue tracker on github. Please always include at the very least the following information:
- The exact version of Vortex you're using
- Your operating system
- What you were doing when the bug happened
- What exactly the bug is (crash? error messages? unexpected behaviour?)
- If you get any error message, include the full and exact error message. Do not paraphrase, do not leave out information that looks cryptic or unimportant to you
- The log file (see below)
- Ideally also the application state (see below)
All data the client generates (including settings and logs) are stored at
C:\Users\<username>\AppData\Roaming\vortex_devel (development build)
If you need to report a bug, the following files inside that directory may be useful in addition to the error message displayed on screen:
- vortex.log (logs are rotated at a certain size, this is the latest one)
- state\* except global_account (that one contains keys and passwords so sensitive information)
- <game>\state* (if the bug pertains to a specific game)