A full-stack dev environment to solve Advent of Code challenges in TypeScript or JavaScript.
Advent of Node is a full webapp stack bundled in an Nx monorepo workspace. The repo includes three apps: solver-app,react-app, express-app.
react-app is a React webapp intended to be built once and served automatically from express-app. The user can open a puzzle to read its description and test their solution using either their puzzle input or a custom input entered on the right side of the UI. Custom inputs can be added, saved, modified, renamed, etc., and are also stored in Mongo alongside the user's provided puzzle input.
express-app is a Node Express API that statically serves the react-app build, fetches data from the AoC website, handles the MongoDB connection, and dispatches solution requests to solver-app. Since express-app handles your AoC account data, it is only configured to be hosted locally or in a private environment.
solver-app is a separate, minimal Node Express application intended as the solution space. It is kept decoupled from express-app to avoid the time sink of rebuilding the full app and recreating the mongo connection on every solution update. By default, starting express-app will spawn an instance of solver-app that supports debugging and auto reloading.
Opening a puzzle for the first time triggers the fetch from AoC, and renders the puzzle description and input pane side-by-side. Solutions should be submitted on the AoC website as normal, but the puzzle description can then be re-fetched using the star button in the upper-right of the UI.
Advent of Node requires the following to run:
- Node.js minimum version 16.20.1
- npm, usually bundled with Node.js
- Yarn (install with
npm install -g yarn)
You will also need to set up a MongoDB instance to store your data. I recommend using MongoDB Atlas, Mongo's free cloud service. The full setup process is documented below.
Advent of Node is configured for development in Visual Studio Code. As an alternative, Jetbrains IDEs are also supported by Nx.
For the best experience, I recommend the Firefox web browser since that's my browser of choice and I've done very little testing on other browsers.
Clone or download the repository, then navigate to the project directory and install required packages by running
yarn
This will install Nx along with all the project's dependencies listed in package.json into the node_modules directory. In general, you will need to rerun the yarn command after any dependency updates to make sure all dependencies are installed and the correct version.
I recommend installing the Nx console extension if it's available in your IDE. In VS Code, you should get a popup asking you to install it along with other recommended extensions.
Prior to running the project, you will need to set some environment variables. There is an .env.example file in express-app to get you started. You will need to add a .env file at the same level and copy two variables from the .env.example.
This session ID is how you get your own account's data from the AoC website. AoC allows you to sign in using your account with another service that supports OAuth, but doesn't offer its own OAuth endpoint (which is probably a good thing). As a result, this is basically the only way for your Advent of Node instance to access account-specific data (like your puzzle input).
- Sign in to https://adventofcode.com
- Open the browser's dev console with F12 and navigate to the "Network" tab.
- Select the first adventofcode.com "GET" request (you may need to refresh the page for the list to populate).
- Under "Cookies", copy the "session" value. This should be a long string representing the hexadecimal value of your sessionId.
- Paste the string into
NX_AOC_SESSIONfield.
This serves as the location of and authentication for your MongoDB instance. You can host your own database locally if you'd like, or create a free account on Atlas: Mongodb's cloud platform. The free tier stores up to 500MB, so this solution should be valid for the next couple of centuries.
Once you've created your account, follow the setup instructions for the Atlas UI to create your own database and set up a database user account Advent of Node can use. From your DB's overview screen, select Connect > Drivers, select Node.js and copy the URL. It should look like:
mongodb+srv://<user>:<password>@<url>/?retryWrites=true&w=majority
Paste the URL into the NX_MONGO_URL variable, making sure to include the password you associated with the account. You can also specify the name of your collection by adding the name to the path. For instance, to name the collection 'adventOfNode', you would use:
mongodb+srv://<user>:<password>@<url>/adventOfNode?retryWrites=true&w=majority
There are a few more environment variables commented out in the example file. These shouldn't be set unless running a non-standard configuration.
By default, express-app spawns a Node child process that runs solver-app locally using Nx's serve configuration.
If you instead want to run solver-app as a completely separate process, setting NX_SOLVER_URL disables the above behavior and tells the app which endpoint to request solutions from.
Set this if you have configured solver-app to listen to API requests on a port besides the default 3000.
This is used to tell the child process which port to allow solver-app debugging on. This defaults to 19229 to match the launch.json configuration, change this if you need the automated process to debug on a different port.
This defaults to "https://adventofcode.com" and should usually not be set unless testing some specific express-app changes.
To build and run Advent of Node, open the Nx Console extension and navigate to the apps directory. To solve puzzles, I recommend running
react-app > build > production
express-app > serve > production
The first step generates the static files for react-app. express-app will then serve them at the default base url of http://localhost:3333 and automatically start the solver-app instance.
After react-app has been built once, you should only need to run the express-app:serve task.
Alternatively, I've set up some build and run tasks in the tasks.json for use in this project. Look there for some guidelines on setting keybindings.
If the Nx Console extension isn't available in your IDE, you will instead need to execute Nx commands from the command line.
yarn nx run react-app:build
yarn nx run express-app:serve
In general, to execute tasks with Nx use the following syntax:
yarn nx <target> <project> <...options>
You can also run multiple targets:
yarn nx run-many -t <target1> <target2>
..or add -p to filter specific projects
yarn nx run-many -t <target1> <target2> -p <proj1> <proj2>
Targets are defined in each project's project.json. Learn more in the Nx docs.
Solutions should be created in the solver library. See its README for documentation on solution stub generation, workflow, and more.
To contribute to Advent of Node, fork this repo and commit your code on a new branch. If your changes require adding a library, I recommend adding one via the Nx Console "generate" option, or referring to the Nx docs. Make sure to set scope/type tags in the generator or in 'project.json'.
The test suite is a WIP, but don't break existing tests and make sure any additions include tests.
Prior to opening a PR, make sure to run the following commands from the Nx Console or from the terminal.
yarn nx affected --target=test
yarn nx affected --target=lint
This project was originally intended for my personal use to solve AoC puzzles, so as a general rule I won't accept changes that modify the workflow without a good reason.
For the same reason, I won't accept additions to the solver or solver-helpers libraries that include any solution code. I maintain my own solutions and helpers in my private repo and encourage anybody using Advent of Node to do the same.
To develop on express-app or react-app or any of their libraries, I recommend running their serve:development tasks (express-app defaults to the 'production' configuration).
Before developing on react-app,you will first need to configure the VITE_EXPRESS_SERVER_URL environment variable in the react-app .env to point to your Express server url. Once you've served the app (default address http://localhost:4200), you can take advantage of Vite's live rebuilds and reloads, as well as the "React" VS Code debug configuration for Edge. Debugging in other browsers is possible with some additional setup.
Advent of Node is licensed under the 3-Clause BSD License.