For maximal consistency, Cuttle can be run with docker (See Docker Instructions).
nodeJs lets you create & run web servers in javascript (along with other fancy system-level stuff not needed for this project). Both the client and server depend on node as the main system-wide dependency. The download comes with npm (node package manager) which you'll use to install the project-specific dependencies.
Currently version 18.xx.xx of node is required as this is the latest stable version of node. You can download node here or use nvm or nvm-windows to manage multiple node versions (recommended for longer term nodejs development).
NOTE When running on your local computer, signup/login only stores credentials on your computer and in memory. Shutting down the server wipes the in-memory database along with all game & account data.
git clone https://github.com/cuttle-cards/cuttle
Or Download as .zip
Open your shell/terminal of choice, cd into the root folder of this repo and run
npm ci
NOTE ci (as opposed to install) is a 'clean install' which ensures versions exactly match package-lock.json.
TIP If npm ci fails, check to make sure you have a C compiler installed on your machine.
You can simultaneously run the server on localhost:1337 and the client on localhost:8080 with one command:
npm run start:dev
npm run start:server
Open another shell/terminal in the root folder of this repo and run
npm run start:client
to start the client on localhost:8080
cuttle.cards uses the vite-plugin vue devtools, which let you inspect application state e.g. viewing all a component's data or all the state in the various stores. This is incredibly useful for debugging and analyzing problems. The devtools are automatically injected into the application during development and can be opened by clicking on the 'vue' icon at the bottom of the page when visiting the application. They can also be opened from inside Cypress tests, which is a powerful combination, enabling you to use test code to force the app into a specific state, and the devtools to investigate and troubleshoot.
Navigate to localhost:8080 in your browser of choice.
You can shut down the client and server by hitting ctrl + c several times from the terminal windows they are running in. Shut down both the client and server to completely delete all game & account data.
From the root directory of the repo, you can run
npm run build
to compile the Vue SPA into the assets directory, which will be statically served by the server (sails backend) at the same port on which it is running to support the API. You can now shut down the client and view the application as its built for production at localhost:1337 (1337 is the default port for sails).
You can build the frontend and boot the backend to serve the latest frontend preview from the sails server at port 1337 with:
npm run start:preview
This will let you see what the production build will look like when served from the backend. This also lets you view the app on other devices connected to the same wifi network by opening any network connected browsers to your-local-ip-address:1337.
While the application (server + client) is running, you can run the entire suite of end-to-end cypress tests against the client running at localhost:8080. This will execute the tests headlessly and output the results in your terminal:
npm run e2e:client
You can also open the cypress UI, which is useful for executing a single test file if you are for example developing a new feature or a fix and want to focus on that aspect of the application (and see how it performs). This is very helpful for localhost development:
npm run e2e:gui
Lastly, you can execute the entire test suite headlessly against localhost:1337. You can use this to test the last-built version of the application. This is effectively what is done in CI when a pull request is submitted against the main branch of this repository:
npm run e2e:server
NOTE you should run npm run build (see above) before this command so that the server (backend) serves the most up-to-date version of the client.
Cuttle has a separate folder of tests that are not intended to be run during CI or for normal development. These tests are used for various tasks and such as creating promotional videos of various moves in the game, or tinkering with repeatedly running test commands to check for flakiness.
The tests reside in tests/e2e/playground/specs. These test files do not appear when running the tests or opening cypress normally.
To see the playground tests in the cypress UI, run npm run e2e:gui:playground.
To run the playground tests headlessly, first build the client with npm run build then run npm run e2e:server:playground.
You can utilize the node debugger in VSCode to debug the backend server.
To do so, you must first start the backend server:
npm run start:server
Then, open the command palette by hitting F1, and then type and select Debug: Attach to node process to select the process you want to watch. Choose the process labeled node app.js as this is the sailsjs server process.
You will be able to utilize many standard debugging features, such as setting breakpoints by clicking line numbers, stepping in and over functions, and watching variables. For details, please refer to the documentation.
Format the project:
npm run lint:fix
Check the formatting without auto-fixing problems. (This is what's run in CI when a PR is opened against the main branch):
npm run lint
Run Storybook locally:
npm run storybook
Storybook will start automatically on localhost:6006 and open a new tab in your browser.
If you are running windows 11 your best option may be to use Windows Subsystem for Linux (WSL)
First you will need to make sure virtualization is enabled in your BIOS
Install WSL
You should now have an icon for "Ubuntu" your app drawer, alternatively you can open up the windows terminal, hit the down arrow and select Ubuntu.
You will need to set your gitconfig email/username, and make a new folder to keep your projects in
You should now be able to setup a repo as described in the Setup section at the top of this page.
**If you have difficulty running Cypress on Linux systems, check the Linux Prerequisites section of the cypress docs