diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile index cb7d00813..ba2df2605 100755 --- a/.devcontainer/Dockerfile +++ b/.devcontainer/Dockerfile @@ -18,13 +18,6 @@ gnupg2 \ iputils-ping \ net-tools \ software-properties-common -RUN curl -fsSL https://www.mongodb.org/static/pgp/server-7.0.asc | apt-key add - -RUN echo "deb [ arch=amd64 ] https://repo.mongodb.org/apt/debian bullseye/mongodb-org/7.0 main" | tee /etc/apt/sources.list.d/mongodb-org-7.0.list -RUN apt-get update -RUN apt-get install -y \ -mongodb-org -RUN sed -i "s,\\(^[[:blank:]]*bindIp:\\) .*,\\1 0.0.0.0," /etc/mongod.conf -RUN sed -i "s,\\(^[[:blank:]]*dbPath:\\) .*,\\1 /workspaces/playnite-web/.mongodb/data," /etc/mongod.conf RUN apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF RUN echo "deb https://download.mono-project.com/repo/debian stable-buster main" > /etc/apt/sources.list.d/mono-official-stable.list diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 5394d2766..c289347e5 100755 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -9,7 +9,7 @@ "version": "7.0.403" }, "ghcr.io/devcontainers/features/node:1": { - "version": "20.9.0", + "version": "22.5.0", "nodeGypDependencies": true }, "ghcr.io/devcontainers/features/powershell:1": {}, @@ -18,9 +18,6 @@ } }, "customizations": { - "devpod": { - "prebuildRepository": "ghcr.io/andrew-codes/playnite-web" - }, "vscode": { "settings": { "terminal.integrated.profiles.linux": { @@ -32,27 +29,38 @@ "workbench.colorTheme": "Dracula Pro" }, "extensions": [ + "apollographql.vscode-apollo", "arcanis.vscode-zipfs", "bierner.github-markdown-preview", "bierner.markdown-yaml-preamble", "capaj.vscode-exports-autocomplete", "cmstead.js-codeformer", "cmstead.jsrefactor", + "codecov.codecov", + "DavidAnson.vscode-markdownlint", "dbaeumer.vscode-eslint", "dracula-theme-pro.theme-dracula-pro", "drKnoxy.eslint-disable-snippets", "eamodio.gitlens", "EditorConfig.EditorConfig", "esbenp.prettier-vscode", + "GitHub.codespaces", "GitHub.copilot-chat", "GitHub.copilot", "github.vscode-github-actions", "GitHub.vscode-pull-request-github", + "GraphQL.vscode-graphql-syntax", "GraphQL.vscode-graphql", + "hbenl.vscode-test-explorer-liveshare", + "hbenl.vscode-test-explorer", "johnuphoff.vscode-styled-sort", "kisstkondoros.vscode-codemetrics", "mikestead.dotenv", + "ms-azuretools.vscode-docker", + "ms-dotnettools.csdevkit", + "ms-dotnettools.csharp", "ms-vscode.powershell", + "ms-vsliveshare.vsliveshare", "Orta.vscode-jest", "paulmolluzzo.convert-css-in-js", "pflannery.vscode-versionlens", @@ -60,7 +68,10 @@ "redhat.vscode-yaml", "rpdswtk.vsmqtt", "sburg.vscode-javascript-booster", + "steoates.autoimport", "streetsidesoftware.code-spell-checker", + "styled-components.vscode-styled-components", + "Terrastruct.d2", "yzhang.markdown-all-in-one" ] } @@ -75,4 +86,4 @@ "containerEnv": { "DISPLAY": "localhost:0" } -} +} \ No newline at end of file diff --git a/.devcontainer/post-create.sh b/.devcontainer/post-create.sh index 5666c9d11..114280e95 100755 --- a/.devcontainer/post-create.sh +++ b/.devcontainer/post-create.sh @@ -7,33 +7,3 @@ echo -e "{ /usr/local/share/docker-init.sh corepack enable -corepack prepare --activate yarn@^4.0.0 - -set -o allexport -. $PWD/local.env -set +o allexport - -mosquitto_passwd -b -c /etc/mosquitto/passwd $MQTT_USERNAME $MQTT_PASSWORD -echo -e "allow_anonymous false -password_file /etc/mosquitto/passwd -listener 1883" >/etc/mosquitto/conf.d/default.conf -mosquitto -c /etc/mosquitto/conf.d/default.conf --daemon --verbose - -mongoDataExists=$(ls .data/mongodb | wc -l) -mkdir -p /.data/mongodb -docker run --name playnite-web-db -d \ - --network host \ - -e MONGO_INITDB_ROOT_USERNAME=$MONGO_INITDB_ROOT_USERNAME \ - -e MONGO_INITDB_ROOT_PASSWORD=$MONGO_INITDB_ROOT_PASSWORD \ - -v $PWD/.data/mongodb:/data/db \ - -v $PWD/.data/games:/data/backup/games \ - mongo:7.0.3-jammy - -if [ $mongoDataExists -eq 0 ]; then - docker exec -t playnite-web-db mongorestore --nsInclude games.* /data/backup -fi - -if [ $(ls apps/playnite-web/public/assets/asset-by-id/ | wc -l) -eq 0 ]; then - echo "Copying development environment game assets" - cp -r .data/asset-by-id/ apps/playnite-web/public/assets -fi diff --git a/.vscode/settings.json b/.vscode/settings.json index c82f2d14b..c228486cf 100755 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -39,5 +39,6 @@ "jest.runMode": { "type": "on-demand", "deferred": true - } -} \ No newline at end of file + }, + "dotnet.preferCSharpExtension": true +} diff --git a/README.md b/README.md index c77bac247..16803094b 100755 --- a/README.md +++ b/README.md @@ -18,6 +18,6 @@ Playnite Web offers: ## Getting Started -1. [Install and run Playnite Web](./docs/guides/setup.md) +1. [Install and run Playnite Web](./docs/documents/guides/setup.md) 2. [Playnite Web API and other documentation](./docs/README.md) -3. [Contributions](./docs/documents/CONTRIBUTING.md) +3. [Contributions](./docs/documents/CONTRIBUTING.md) and [local development environment](./docs/documents/contributing/development-environment) diff --git a/_docs/contributing/development-environment.md b/_docs/contributing/development-environment.md deleted file mode 100755 index acd970997..000000000 --- a/_docs/contributing/development-environment.md +++ /dev/null @@ -1,88 +0,0 @@ -# Development Environment - -- [Development Environment](#development-environment) - - [Overview](#overview) - - [Setup: Directly on Local Machine (preferred)](#setup-directly-on-local-machine-preferred) - - [Directly: Required Software](#directly-required-software) - - [Directly: Preparing Codebase](#directly-preparing-codebase) - - [Running Locally](#running-locally) - - [Setup: Devcontainer (milage may vary)](#setup-devcontainer-milage-may-vary) - - [Devcontainer: Required Software](#devcontainer-required-software) - - [Devcontainer: Preparing Codebase](#devcontainer-preparing-codebase) - -## Overview - -There are a few options for running Playnite Web for local development. The options are: - -- via Docker and the included dev container (includes everything you need to run and develop). -- directly on your development machine (requires installing required tooling such as Node.js, yarn, etc.). -- via a GitHub codespace. - -## Setup: Directly on Local Machine (preferred) - -### Directly: Required Software - -Install the following software on your local development machine: - -1. git -2. Bash (this guide assumes a bash shell) -3. [vscode](https://code.visualstudio.com/Download) -4. [Docker](https://www.docker.com/products/docker-desktop/) (for Mongodb and MQTT dependencies) -5. [Node.js@>=22.5.0](https://nodejs.org/en/download/package-manager) (recommend using `nvm` to manage Node.js installations) - - [nvm for OSX](https://github.com/nvm-sh/nvm) - - [nvm for Windows](https://github.com/coreybutler/nvm-windows) -6. [yarn@^4.0.0](https://yarnpkg.com/getting-started) - - With Node.js installed, run `corepack enable && corepack prepare --activate yarn@^4.0.0 && yarn set version berry` - -### Directly: Preparing Codebase - -1. [Fork the playnite-web repo](https://github.com/andrew-codes/playnite-web/fork) -2. Clone your forked repo to your local development machine. -3. Open the repo in vscode. -4. Run `yarn` -5. Run `yarn nx run devenv:prepare`. This is only required for the first time working with the codebase. -6. Run `yarn run start` and navigate to [https://localhost:3000](https://localhost:3000) - - Note that MQTT and Mongo will be started via docker automatically. - - Mongo will restore a default database if no database already exists (if there are no files in `.data/mongodb`). - - Note MQTT currently starts with no username/password configured. -7. \[Optional\]: override environment variables when running locally via `cp apps/playnite-web/local.env apps/playnite-web/overrides.env` - - **REMEMBER: do not commit `overrides.env` or sensitive information in `local.env`.** - -## Running Locally - -| Application | Command | Notes | -| :--------------- | :-------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Playnite Web App | `yarn run start` | Run Playnite Web application locally. Navigate to [https://localhost:3000](https://localhost:3000) in a browser. Environment variables are pulled from `./apps/playnite-web/local.env`. | -| Playnite Web App | `yarn run test/components` | Run component tests for development. | -| Playnite Web App | `yarn run test/components/update` | Run component tests with intention to update a baseline screenshot. | -| Playnite Web App | `yarn yarn run test/e2e` | Run end-to-end (e2e) tests for development (including visual regression capabilities). A consistent database restored along with consistent game assets. This ensures a reliable data set to test against. | -| Playnite Web App | `yarn yarn run test/e2e/update` | Run end-to-end (e2e) tests with intention to update a baseline screenshot. | - -## Setup: Devcontainer (milage may vary) - -### Devcontainer: Required Software - -Install the following software on your local development machine: - -1. git -2. Bash (this guide assumes a bash shell) -3. [vscode](https://code.visualstudio.com/Download) -4. [Docker](https://www.docker.com/products/docker-desktop/) -5. vscode [Devcontainers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) -6. XServer (for running Cypress tests in container). - - For OSX, recommend: [XQuartz](https://www.bing.com/ck/a?!&&p=c21da4f99329c03fJmltdHM9MTcxODg0MTYwMCZpZ3VpZD0zOTJjZTBlOC1iMzRjLTY3Y2MtMDU4NC1mM2NkYjI2MDY2NjUmaW5zaWQ9NTIyNw&ptn=3&ver=2&hsh=3&fclid=392ce0e8-b34c-67cc-0584-f3cdb2606665&psq=xquartz+&u=a1aHR0cHM6Ly93d3cueHF1YXJ0ei5vcmcv&ntb=1) - - For Windows, still need a recommendation. - -### Devcontainer: Preparing Codebase - -1. [Fork the playnite-web repo](https://github.com/andrew-codes/playnite-web/fork) -2. Clone your forked repo to your local development machine. -3. Open the repo in vscode. -4. Run `yarn` -5. Ensure your XServer application is running (if running Cypress tests). - - Ensure your XServer is configured to Authenticate and Allow Connections from network clients -6. Once in vscode, Devcontainers: Rebuild and Reopen in container. - - This can be done via the command palette (`Cmd + Shift + P`/`Ctrl + Shift + P`) and typing in `Rebuild and reopen in container`. - - This will build a docker image based on the repo's `.devcontainer/Dockerfile`, start, and then open the repo in that container. - -Note that MongoDB and Mosquitto (MQTT) are already setup and installed for localhost when using a devcontainer. See the `./local.env` file for their connection details. diff --git a/_docs/contributing/development-environment/codespaces.md b/_docs/contributing/development-environment/codespaces.md new file mode 100644 index 000000000..57668913c --- /dev/null +++ b/_docs/contributing/development-environment/codespaces.md @@ -0,0 +1,22 @@ +# Developer Environment: Codespace + +## Required Software + +Install the following software on your local machine: + +1. [vscode](https://code.visualstudio.com/Download) +2. XServer (for running Cypress tests in codespace). + - For OSX, recommend: [XQuartz](https://www.bing.com/ck/a?!&&p=c21da4f99329c03fJmltdHM9MTcxODg0MTYwMCZpZ3VpZD0zOTJjZTBlOC1iMzRjLTY3Y2MtMDU4NC1mM2NkYjI2MDY2NjUmaW5zaWQ9NTIyNw&ptn=3&ver=2&hsh=3&fclid=392ce0e8-b34c-67cc-0584-f3cdb2606665&psq=xquartz+&u=a1aHR0cHM6Ly93d3cueHF1YXJ0ei5vcmcv&ntb=1) + - For Windows, still need a recommendation. + +## Preparing Codebase + +1. [Fork the playnite-web repo](https://github.com/andrew-codes/playnite-web/fork) +2. Ensure your XServer application is running on local machine. + - Ensure your XServer is configured to Authenticate and Allow Connections from network clients +3. Start a codespace and open in vscode. +4. Run `yarn` +5. Run `yarn run start` +6. In vscode, forward port 3000. This can be found in same pane as the terminal. +7. Open [http://localhost:3000](http://localhost:3000). +8. Continue to see [commands](./index.md#running-playnite-web) for running tests. diff --git a/_docs/contributing/development-environment/index.md b/_docs/contributing/development-environment/index.md new file mode 100755 index 000000000..4ad1bd6b0 --- /dev/null +++ b/_docs/contributing/development-environment/index.md @@ -0,0 +1,38 @@ +# Development Environment + +- [Development Environment](#development-environment) + - [Overview](#overview) + - [Running Playnite Web](#running-playnite-web) + - [Playnite Web Plugin Development](#playnite-web-plugin-development) + +## Overview + +There are a few options for running Playnite Web for local development. Choose and follow one of the paths below. Then proceed to the next section. + +1. (preferred) [Local environment](./local-environment.md), directly on your development machine (requires installing required tooling such as Node.js, yarn, etc.). +2. Via a GitHub codespace (the plugin cannot be run this way). +3. Via Docker and the included dev container (the plugin cannot be run this way). + +> Note the second and third options maybe encounter issues or additional configuration when running component and E2E tests. + +## Running Playnite Web + +| Application | Command | Notes | +| :--------------- | :-------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Playnite Web App | `yarn run start` | Run Playnite Web application locally. Navigate to [https://localhost:3000](https://localhost:3000) in a browser. Environment variables are pulled from `./apps/playnite-web/local.env`. | +| Playnite Web App | `yarn run test/components` | Run component tests for development. | +| Playnite Web App | `yarn run test/components/update` | Run component tests with intention to update a baseline screenshot. | +| Playnite Web App | `yarn yarn run test/e2e` | Run end-to-end (e2e) tests for development (including visual regression capabilities). A consistent database restored along with consistent game assets. This ensures a reliable data set to test against. | +| Playnite Web App | `yarn yarn run test/e2e/update` | Run end-to-end (e2e) tests with intention to update a baseline screenshot. | + +## Playnite Web Plugin Development + +To develop the Playnite Web plugin, a Windows machine is required. Playnite must be installed. Recommendation is to use Visual Studio Community edition for development. + +1. Install required software + - Playnite + - Visual Studio +2. Open the solution file in Visual Studio; located in `apps/PlayniteWebPlugin/src/PlayniteWeb.sln`. +3. Build the solution. +4. Open Playnite and add the path to the bin directory as a local plugin. This setting is found under the Developer section in the settings. +5. Debugging opens Playnite with the plugin installed. diff --git a/_docs/contributing/development-environment/local-environment.md b/_docs/contributing/development-environment/local-environment.md new file mode 100644 index 000000000..2b92a3a26 --- /dev/null +++ b/_docs/contributing/development-environment/local-environment.md @@ -0,0 +1,30 @@ +# Developer Environment: Local + +## Required Software + +Install the following software on your local development machine: + +1. git +2. Bash (this guide assumes a bash shell) +3. [vscode](https://code.visualstudio.com/Download) +4. [Docker](https://www.docker.com/products/docker-desktop/) (for Mongodb and MQTT dependencies) +5. [Node.js@>=22.5.0](https://nodejs.org/en/download/package-manager) (recommend using `nvm` to manage Node.js installations) + - [nvm for OSX](https://github.com/nvm-sh/nvm) + - [nvm for Windows](https://github.com/coreybutler/nvm-windows) +6. [yarn@^4.0.0](https://yarnpkg.com/getting-started) + - With Node.js installed, run `corepack enable && corepack prepare --activate yarn@^4.0.0 && yarn set version berry` + +## Preparing Codebase + +1. [Fork the playnite-web repo](https://github.com/andrew-codes/playnite-web/fork) +2. Clone your forked repo to your local development machine. +3. Open the repo in vscode. +4. Run `yarn` +5. Run `yarn nx run devenv:prepare`. This is only required for the first time working with the codebase. +6. Run `yarn run start` and navigate to [https://localhost:3000](https://localhost:3000) + - Note that MQTT and Mongo will be started via docker automatically. + - Mongo will restore a default database if no database already exists (if there are no files in `.data/mongodb`). + - Note MQTT currently starts with no username/password configured. +7. \[Optional\]: override environment variables when running locally via `cp apps/playnite-web/local.env apps/playnite-web/overrides.env` + - **REMEMBER: do not commit `overrides.env` or sensitive information in `local.env`.** +8. Continue to see [commands](./index.md#running-playnite-web) for running tests. diff --git a/apps/playnite-web/project.json b/apps/playnite-web/project.json index df9490e99..5f7dd0e21 100755 --- a/apps/playnite-web/project.json +++ b/apps/playnite-web/project.json @@ -28,7 +28,7 @@ "executor": "nx:run-commands", "options": { "cwd": "{projectRoot}", - "command": "yarn cross-env NODE_ENV=development yarn node --experimental-json-modules scripts/utils/startDevServer.js" + "command": "yarn cross-env NODE_ENV=development DEBUG='playnite*' yarn node --experimental-json-modules scripts/utils/startDevServer.js" } }, "test/unit": { diff --git a/docs/README.md b/docs/README.md index 23e7749df..37698413e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -10,7 +10,9 @@ - [api/mqtt](documents/api/mqtt.md) - [CONTRIBUTING](documents/CONTRIBUTING.md) - [contributing/conventions](documents/contributing/conventions.md) -- [contributing/development-environment](documents/contributing/development-environment.md) +- [contributing/development-environment/codespaces](documents/contributing/development-environment/codespaces.md) +- [contributing/development-environment/index](documents/contributing/development-environment/index.md) +- [contributing/development-environment/local-environment](documents/contributing/development-environment/local-environment.md) - [contributing/rfc](documents/contributing/rfc.md) - [design/README](documents/design/README.md) - [guides/setup](documents/guides/setup.md) diff --git a/docs/documents/contributing/development-environment.md b/docs/documents/contributing/development-environment.md deleted file mode 100644 index f4932e491..000000000 --- a/docs/documents/contributing/development-environment.md +++ /dev/null @@ -1,94 +0,0 @@ -[**playnite-web-app**](../../README.md) • **Docs** - -*** - -[playnite-web-app](../../README.md) / contributing/development-environment - -# Development Environment - -- [Development Environment](#development-environment) - - [Overview](#overview) - - [Setup: Directly on Local Machine (preferred)](#setup-directly-on-local-machine-preferred) - - [Directly: Required Software](#directly-required-software) - - [Directly: Preparing Codebase](#directly-preparing-codebase) - - [Running Locally](#running-locally) - - [Setup: Devcontainer (milage may vary)](#setup-devcontainer-milage-may-vary) - - [Devcontainer: Required Software](#devcontainer-required-software) - - [Devcontainer: Preparing Codebase](#devcontainer-preparing-codebase) - -## Overview - -There are a few options for running Playnite Web for local development. The options are: - -- via Docker and the included dev container (includes everything you need to run and develop). -- directly on your development machine (requires installing required tooling such as Node.js, yarn, etc.). -- via a GitHub codespace. - -## Setup: Directly on Local Machine (preferred) - -### Directly: Required Software - -Install the following software on your local development machine: - -1. git -2. Bash (this guide assumes a bash shell) -3. [vscode](https://code.visualstudio.com/Download) -4. [Docker](https://www.docker.com/products/docker-desktop/) (for Mongodb and MQTT dependencies) -5. [Node.js@>=22.5.0](https://nodejs.org/en/download/package-manager) (recommend using `nvm` to manage Node.js installations) - - [nvm for OSX](https://github.com/nvm-sh/nvm) - - [nvm for Windows](https://github.com/coreybutler/nvm-windows) -6. [yarn@^4.0.0](https://yarnpkg.com/getting-started) - - With Node.js installed, run `corepack enable && corepack prepare --activate yarn@^4.0.0 && yarn set version berry` - -### Directly: Preparing Codebase - -1. [Fork the playnite-web repo](https://github.com/andrew-codes/playnite-web/fork) -2. Clone your forked repo to your local development machine. -3. Open the repo in vscode. -4. Run `yarn` -5. Run `yarn nx run devenv:prepare`. This is only required for the first time working with the codebase. -6. Run `yarn run start` and navigate to [https://localhost:3000](https://localhost:3000) - - Note that MQTT and Mongo will be started via docker automatically. - - Mongo will restore a default database if no database already exists (if there are no files in `.data/mongodb`). - - Note MQTT currently starts with no username/password configured. -7. \[Optional\]: override environment variables when running locally via `cp apps/playnite-web/local.env apps/playnite-web/overrides.env` - - **REMEMBER: do not commit `overrides.env` or sensitive information in `local.env`.** - -## Running Locally - -| Application | Command | Notes | -| :--------------- | :-------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Playnite Web App | `yarn run start` | Run Playnite Web application locally. Navigate to [https://localhost:3000](https://localhost:3000) in a browser. Environment variables are pulled from `./apps/playnite-web/local.env`. | -| Playnite Web App | `yarn run test/components` | Run component tests for development. | -| Playnite Web App | `yarn run test/components/update` | Run component tests with intention to update a baseline screenshot. | -| Playnite Web App | `yarn yarn run test/e2e` | Run end-to-end (e2e) tests for development (including visual regression capabilities). A consistent database restored along with consistent game assets. This ensures a reliable data set to test against. | -| Playnite Web App | `yarn yarn run test/e2e/update` | Run end-to-end (e2e) tests with intention to update a baseline screenshot. | - -## Setup: Devcontainer (milage may vary) - -### Devcontainer: Required Software - -Install the following software on your local development machine: - -1. git -2. Bash (this guide assumes a bash shell) -3. [vscode](https://code.visualstudio.com/Download) -4. [Docker](https://www.docker.com/products/docker-desktop/) -5. vscode [Devcontainers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) -6. XServer (for running Cypress tests in container). - - For OSX, recommend: [XQuartz](https://www.bing.com/ck/a?!&&p=c21da4f99329c03fJmltdHM9MTcxODg0MTYwMCZpZ3VpZD0zOTJjZTBlOC1iMzRjLTY3Y2MtMDU4NC1mM2NkYjI2MDY2NjUmaW5zaWQ9NTIyNw&ptn=3&ver=2&hsh=3&fclid=392ce0e8-b34c-67cc-0584-f3cdb2606665&psq=xquartz+&u=a1aHR0cHM6Ly93d3cueHF1YXJ0ei5vcmcv&ntb=1) - - For Windows, still need a recommendation. - -### Devcontainer: Preparing Codebase - -1. [Fork the playnite-web repo](https://github.com/andrew-codes/playnite-web/fork) -2. Clone your forked repo to your local development machine. -3. Open the repo in vscode. -4. Run `yarn` -5. Ensure your XServer application is running (if running Cypress tests). - - Ensure your XServer is configured to Authenticate and Allow Connections from network clients -6. Once in vscode, Devcontainers: Rebuild and Reopen in container. - - This can be done via the command palette (`Cmd + Shift + P`/`Ctrl + Shift + P`) and typing in `Rebuild and reopen in container`. - - This will build a docker image based on the repo's `.devcontainer/Dockerfile`, start, and then open the repo in that container. - -Note that MongoDB and Mosquitto (MQTT) are already setup and installed for localhost when using a devcontainer. See the `./local.env` file for their connection details. diff --git a/docs/documents/contributing/development-environment/codespaces.md b/docs/documents/contributing/development-environment/codespaces.md new file mode 100644 index 000000000..0c96f2c67 --- /dev/null +++ b/docs/documents/contributing/development-environment/codespaces.md @@ -0,0 +1,28 @@ +[**playnite-web-app**](../../../README.md) • **Docs** + +*** + +[playnite-web-app](../../../README.md) / contributing/development-environment/codespaces + +# Developer Environment: Codespace + +## Required Software + +Install the following software on your local machine: + +1. [vscode](https://code.visualstudio.com/Download) +2. XServer (for running Cypress tests in codespace). + - For OSX, recommend: [XQuartz](https://www.bing.com/ck/a?!&&p=c21da4f99329c03fJmltdHM9MTcxODg0MTYwMCZpZ3VpZD0zOTJjZTBlOC1iMzRjLTY3Y2MtMDU4NC1mM2NkYjI2MDY2NjUmaW5zaWQ9NTIyNw&ptn=3&ver=2&hsh=3&fclid=392ce0e8-b34c-67cc-0584-f3cdb2606665&psq=xquartz+&u=a1aHR0cHM6Ly93d3cueHF1YXJ0ei5vcmcv&ntb=1) + - For Windows, still need a recommendation. + +## Preparing Codebase + +1. [Fork the playnite-web repo](https://github.com/andrew-codes/playnite-web/fork) +2. Ensure your XServer application is running on local machine. + - Ensure your XServer is configured to Authenticate and Allow Connections from network clients +3. Start a codespace and open in vscode. +4. Run `yarn` +5. Run `yarn run start` +6. In vscode, forward port 3000. This can be found in same pane as the terminal. +7. Open [http://localhost:3000](http://localhost:3000). +8. Continue to see [commands](./index.md#running-playnite-web) for running tests. diff --git a/docs/documents/contributing/development-environment/index.md b/docs/documents/contributing/development-environment/index.md new file mode 100644 index 000000000..3fa67f64d --- /dev/null +++ b/docs/documents/contributing/development-environment/index.md @@ -0,0 +1,44 @@ +[**playnite-web-app**](../../../README.md) • **Docs** + +*** + +[playnite-web-app](../../../README.md) / contributing/development-environment/index + +# Development Environment + +- [Development Environment](#development-environment) + - [Overview](#overview) + - [Running Playnite Web](#running-playnite-web) + - [Playnite Web Plugin Development](#playnite-web-plugin-development) + +## Overview + +There are a few options for running Playnite Web for local development. Choose and follow one of the paths below. Then proceed to the next section. + +1. (preferred) [Local environment](local-environment.md), directly on your development machine (requires installing required tooling such as Node.js, yarn, etc.). +2. Via a GitHub codespace (the plugin cannot be run this way). +3. Via Docker and the included dev container (the plugin cannot be run this way). + +> Note the second and third options maybe encounter issues or additional configuration when running component and E2E tests. + +## Running Playnite Web + +| Application | Command | Notes | +| :--------------- | :-------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Playnite Web App | `yarn run start` | Run Playnite Web application locally. Navigate to [https://localhost:3000](https://localhost:3000) in a browser. Environment variables are pulled from `./apps/playnite-web/local.env`. | +| Playnite Web App | `yarn run test/components` | Run component tests for development. | +| Playnite Web App | `yarn run test/components/update` | Run component tests with intention to update a baseline screenshot. | +| Playnite Web App | `yarn yarn run test/e2e` | Run end-to-end (e2e) tests for development (including visual regression capabilities). A consistent database restored along with consistent game assets. This ensures a reliable data set to test against. | +| Playnite Web App | `yarn yarn run test/e2e/update` | Run end-to-end (e2e) tests with intention to update a baseline screenshot. | + +## Playnite Web Plugin Development + +To develop the Playnite Web plugin, a Windows machine is required. Playnite must be installed. Recommendation is to use Visual Studio Community edition for development. + +1. Install required software + - Playnite + - Visual Studio +2. Open the solution file in Visual Studio; located in `apps/PlayniteWebPlugin/src/PlayniteWeb.sln`. +3. Build the solution. +4. Open Playnite and add the path to the bin directory as a local plugin. This setting is found under the Developer section in the settings. +5. Debugging opens Playnite with the plugin installed. diff --git a/docs/documents/contributing/development-environment/local-environment.md b/docs/documents/contributing/development-environment/local-environment.md new file mode 100644 index 000000000..9b3dae3ac --- /dev/null +++ b/docs/documents/contributing/development-environment/local-environment.md @@ -0,0 +1,36 @@ +[**playnite-web-app**](../../../README.md) • **Docs** + +*** + +[playnite-web-app](../../../README.md) / contributing/development-environment/local-environment + +# Developer Environment: Local + +## Required Software + +Install the following software on your local development machine: + +1. git +2. Bash (this guide assumes a bash shell) +3. [vscode](https://code.visualstudio.com/Download) +4. [Docker](https://www.docker.com/products/docker-desktop/) (for Mongodb and MQTT dependencies) +5. [Node.js@>=22.5.0](https://nodejs.org/en/download/package-manager) (recommend using `nvm` to manage Node.js installations) + - [nvm for OSX](https://github.com/nvm-sh/nvm) + - [nvm for Windows](https://github.com/coreybutler/nvm-windows) +6. [yarn@^4.0.0](https://yarnpkg.com/getting-started) + - With Node.js installed, run `corepack enable && corepack prepare --activate yarn@^4.0.0 && yarn set version berry` + +## Preparing Codebase + +1. [Fork the playnite-web repo](https://github.com/andrew-codes/playnite-web/fork) +2. Clone your forked repo to your local development machine. +3. Open the repo in vscode. +4. Run `yarn` +5. Run `yarn nx run devenv:prepare`. This is only required for the first time working with the codebase. +6. Run `yarn run start` and navigate to [https://localhost:3000](https://localhost:3000) + - Note that MQTT and Mongo will be started via docker automatically. + - Mongo will restore a default database if no database already exists (if there are no files in `.data/mongodb`). + - Note MQTT currently starts with no username/password configured. +7. \[Optional\]: override environment variables when running locally via `cp apps/playnite-web/local.env apps/playnite-web/overrides.env` + - **REMEMBER: do not commit `overrides.env` or sensitive information in `local.env`.** +8. Continue to see [commands](./index.md#running-playnite-web) for running tests. diff --git a/docs/types.entities/type-aliases/CompletionStatus.md b/docs/types.entities/type-aliases/CompletionStatus.md index 2cee6fb02..993675b07 100644 --- a/docs/types.entities/type-aliases/CompletionStatus.md +++ b/docs/types.entities/type-aliases/CompletionStatus.md @@ -26,4 +26,4 @@ Completion statuses are used to describe a player's progress in a game. ## Defined in -[types.entities.ts:184](https://github.com/andrew-codes/playnite-web/blob/f4b196c836ff1f14161b4d04346bf7c194eb1fa5/apps/playnite-web/src/server/data/types.entities.ts#L184) +[types.entities.ts:184](https://github.com/andrew-codes/playnite-web/blob/8e4fb0564dac8f04f0ec7b3de8bb1500c246dd52/apps/playnite-web/src/server/data/types.entities.ts#L184) diff --git a/docs/types.entities/type-aliases/Entity.md b/docs/types.entities/type-aliases/Entity.md index 89e127955..053045b9d 100644 --- a/docs/types.entities/type-aliases/Entity.md +++ b/docs/types.entities/type-aliases/Entity.md @@ -12,4 +12,4 @@ Supported entities. ## Defined in -[types.entities.ts:96](https://github.com/andrew-codes/playnite-web/blob/f4b196c836ff1f14161b4d04346bf7c194eb1fa5/apps/playnite-web/src/server/data/types.entities.ts#L96) +[types.entities.ts:96](https://github.com/andrew-codes/playnite-web/blob/8e4fb0564dac8f04f0ec7b3de8bb1500c246dd52/apps/playnite-web/src/server/data/types.entities.ts#L96) diff --git a/docs/types.entities/type-aliases/Game.md b/docs/types.entities/type-aliases/Game.md index 3d03ac8ea..068f41597 100644 --- a/docs/types.entities/type-aliases/Game.md +++ b/docs/types.entities/type-aliases/Game.md @@ -41,4 +41,4 @@ A game may have multiple releases across different platforms and sources. ## Defined in -[types.entities.ts:220](https://github.com/andrew-codes/playnite-web/blob/f4b196c836ff1f14161b4d04346bf7c194eb1fa5/apps/playnite-web/src/server/data/types.entities.ts#L220) +[types.entities.ts:220](https://github.com/andrew-codes/playnite-web/blob/8e4fb0564dac8f04f0ec7b3de8bb1500c246dd52/apps/playnite-web/src/server/data/types.entities.ts#L220) diff --git a/docs/types.entities/type-aliases/GameAsset.md b/docs/types.entities/type-aliases/GameAsset.md index c60e44c37..3d7713922 100644 --- a/docs/types.entities/type-aliases/GameAsset.md +++ b/docs/types.entities/type-aliases/GameAsset.md @@ -34,4 +34,4 @@ Game assets are used to associate images with entities. ## Defined in -[types.entities.ts:327](https://github.com/andrew-codes/playnite-web/blob/f4b196c836ff1f14161b4d04346bf7c194eb1fa5/apps/playnite-web/src/server/data/types.entities.ts#L327) +[types.entities.ts:327](https://github.com/andrew-codes/playnite-web/blob/8e4fb0564dac8f04f0ec7b3de8bb1500c246dd52/apps/playnite-web/src/server/data/types.entities.ts#L327) diff --git a/docs/types.entities/type-aliases/GameAssetType.md b/docs/types.entities/type-aliases/GameAssetType.md index 2f29b8c68..e54d47609 100644 --- a/docs/types.entities/type-aliases/GameAssetType.md +++ b/docs/types.entities/type-aliases/GameAssetType.md @@ -22,4 +22,4 @@ Game asset types represent the types of game assets that can be associated with ## Defined in -[types.entities.ts:317](https://github.com/andrew-codes/playnite-web/blob/f4b196c836ff1f14161b4d04346bf7c194eb1fa5/apps/playnite-web/src/server/data/types.entities.ts#L317) +[types.entities.ts:317](https://github.com/andrew-codes/playnite-web/blob/8e4fb0564dac8f04f0ec7b3de8bb1500c246dd52/apps/playnite-web/src/server/data/types.entities.ts#L317) diff --git a/docs/types.entities/type-aliases/GameFeature.md b/docs/types.entities/type-aliases/GameFeature.md index c82986446..45d33dabc 100644 --- a/docs/types.entities/type-aliases/GameFeature.md +++ b/docs/types.entities/type-aliases/GameFeature.md @@ -26,4 +26,4 @@ Features are used to describe a game's characteristics. ## Defined in -[types.entities.ts:162](https://github.com/andrew-codes/playnite-web/blob/f4b196c836ff1f14161b4d04346bf7c194eb1fa5/apps/playnite-web/src/server/data/types.entities.ts#L162) +[types.entities.ts:162](https://github.com/andrew-codes/playnite-web/blob/8e4fb0564dac8f04f0ec7b3de8bb1500c246dd52/apps/playnite-web/src/server/data/types.entities.ts#L162) diff --git a/docs/types.entities/type-aliases/GameSource.md b/docs/types.entities/type-aliases/GameSource.md index d746774ed..c34d226b6 100644 --- a/docs/types.entities/type-aliases/GameSource.md +++ b/docs/types.entities/type-aliases/GameSource.md @@ -26,4 +26,4 @@ Sources are used to describe where a game was obtained. ## Defined in -[types.entities.ts:206](https://github.com/andrew-codes/playnite-web/blob/f4b196c836ff1f14161b4d04346bf7c194eb1fa5/apps/playnite-web/src/server/data/types.entities.ts#L206) +[types.entities.ts:206](https://github.com/andrew-codes/playnite-web/blob/8e4fb0564dac8f04f0ec7b3de8bb1500c246dd52/apps/playnite-web/src/server/data/types.entities.ts#L206) diff --git a/docs/types.entities/type-aliases/Genre.md b/docs/types.entities/type-aliases/Genre.md index c8bb76acf..0d31d1079 100644 --- a/docs/types.entities/type-aliases/Genre.md +++ b/docs/types.entities/type-aliases/Genre.md @@ -26,4 +26,4 @@ Genres are used to categorize games by their game play characteristics. ## Defined in -[types.entities.ts:173](https://github.com/andrew-codes/playnite-web/blob/f4b196c836ff1f14161b4d04346bf7c194eb1fa5/apps/playnite-web/src/server/data/types.entities.ts#L173) +[types.entities.ts:173](https://github.com/andrew-codes/playnite-web/blob/8e4fb0564dac8f04f0ec7b3de8bb1500c246dd52/apps/playnite-web/src/server/data/types.entities.ts#L173) diff --git a/docs/types.entities/type-aliases/Identifiable.md b/docs/types.entities/type-aliases/Identifiable.md index a729eb6e0..ad786eddb 100644 --- a/docs/types.entities/type-aliases/Identifiable.md +++ b/docs/types.entities/type-aliases/Identifiable.md @@ -18,4 +18,4 @@ Foundation of all data entities; all data entities have an ID. ## Defined in -[types.entities.ts:4](https://github.com/andrew-codes/playnite-web/blob/f4b196c836ff1f14161b4d04346bf7c194eb1fa5/apps/playnite-web/src/server/data/types.entities.ts#L4) +[types.entities.ts:4](https://github.com/andrew-codes/playnite-web/blob/8e4fb0564dac8f04f0ec7b3de8bb1500c246dd52/apps/playnite-web/src/server/data/types.entities.ts#L4) diff --git a/docs/types.entities/type-aliases/Platform.md b/docs/types.entities/type-aliases/Platform.md index cbe075989..83bf389e1 100644 --- a/docs/types.entities/type-aliases/Platform.md +++ b/docs/types.entities/type-aliases/Platform.md @@ -60,4 +60,4 @@ Platforms are used to categorize games by the system they are played on. Note a ## Defined in -[types.entities.ts:116](https://github.com/andrew-codes/playnite-web/blob/f4b196c836ff1f14161b4d04346bf7c194eb1fa5/apps/playnite-web/src/server/data/types.entities.ts#L116) +[types.entities.ts:116](https://github.com/andrew-codes/playnite-web/blob/8e4fb0564dac8f04f0ec7b3de8bb1500c246dd52/apps/playnite-web/src/server/data/types.entities.ts#L116) diff --git a/docs/types.entities/type-aliases/Playlist.md b/docs/types.entities/type-aliases/Playlist.md index 97b9d7901..053058741 100644 --- a/docs/types.entities/type-aliases/Playlist.md +++ b/docs/types.entities/type-aliases/Playlist.md @@ -36,4 +36,4 @@ Playlists are used to group games together for easy access. A playlist consists ## Defined in -[types.entities.ts:299](https://github.com/andrew-codes/playnite-web/blob/f4b196c836ff1f14161b4d04346bf7c194eb1fa5/apps/playnite-web/src/server/data/types.entities.ts#L299) +[types.entities.ts:299](https://github.com/andrew-codes/playnite-web/blob/8e4fb0564dac8f04f0ec7b3de8bb1500c246dd52/apps/playnite-web/src/server/data/types.entities.ts#L299) diff --git a/docs/types.entities/type-aliases/Release.md b/docs/types.entities/type-aliases/Release.md index 1485cde5a..e1c7a774a 100644 --- a/docs/types.entities/type-aliases/Release.md +++ b/docs/types.entities/type-aliases/Release.md @@ -152,4 +152,4 @@ A release is a specific version of a game that is available on a platform and so ## Defined in -[types.entities.ts:255](https://github.com/andrew-codes/playnite-web/blob/f4b196c836ff1f14161b4d04346bf7c194eb1fa5/apps/playnite-web/src/server/data/types.entities.ts#L255) +[types.entities.ts:255](https://github.com/andrew-codes/playnite-web/blob/8e4fb0564dac8f04f0ec7b3de8bb1500c246dd52/apps/playnite-web/src/server/data/types.entities.ts#L255) diff --git a/docs/types.entities/type-aliases/RunState.md b/docs/types.entities/type-aliases/RunState.md index 1a5570775..9b43cef8a 100644 --- a/docs/types.entities/type-aliases/RunState.md +++ b/docs/types.entities/type-aliases/RunState.md @@ -22,4 +22,4 @@ Run states are used to describe the current state of a game's process. ## Defined in -[types.entities.ts:247](https://github.com/andrew-codes/playnite-web/blob/f4b196c836ff1f14161b4d04346bf7c194eb1fa5/apps/playnite-web/src/server/data/types.entities.ts#L247) +[types.entities.ts:247](https://github.com/andrew-codes/playnite-web/blob/8e4fb0564dac8f04f0ec7b3de8bb1500c246dd52/apps/playnite-web/src/server/data/types.entities.ts#L247) diff --git a/docs/types.entities/type-aliases/Series.md b/docs/types.entities/type-aliases/Series.md index 3ec5dbdf6..632effa6b 100644 --- a/docs/types.entities/type-aliases/Series.md +++ b/docs/types.entities/type-aliases/Series.md @@ -32,4 +32,4 @@ The "Assassin's Creed" series would include all games in the "Assassin's Creed" ## Defined in -[types.entities.ts:151](https://github.com/andrew-codes/playnite-web/blob/f4b196c836ff1f14161b4d04346bf7c194eb1fa5/apps/playnite-web/src/server/data/types.entities.ts#L151) +[types.entities.ts:151](https://github.com/andrew-codes/playnite-web/blob/8e4fb0564dac8f04f0ec7b3de8bb1500c246dd52/apps/playnite-web/src/server/data/types.entities.ts#L151) diff --git a/docs/types.entities/type-aliases/Tag.md b/docs/types.entities/type-aliases/Tag.md index 617efa45f..0793bc02e 100644 --- a/docs/types.entities/type-aliases/Tag.md +++ b/docs/types.entities/type-aliases/Tag.md @@ -26,4 +26,4 @@ Tags are used to categorize games by their characteristics. ## Defined in -[types.entities.ts:195](https://github.com/andrew-codes/playnite-web/blob/f4b196c836ff1f14161b4d04346bf7c194eb1fa5/apps/playnite-web/src/server/data/types.entities.ts#L195) +[types.entities.ts:195](https://github.com/andrew-codes/playnite-web/blob/8e4fb0564dac8f04f0ec7b3de8bb1500c246dd52/apps/playnite-web/src/server/data/types.entities.ts#L195) diff --git a/docs/types.entities/type-aliases/User.md b/docs/types.entities/type-aliases/User.md index a23d0d468..29daadcad 100644 --- a/docs/types.entities/type-aliases/User.md +++ b/docs/types.entities/type-aliases/User.md @@ -34,4 +34,4 @@ Users are used to authenticate and authorize access to the application. ## Defined in -[types.entities.ts:340](https://github.com/andrew-codes/playnite-web/blob/f4b196c836ff1f14161b4d04346bf7c194eb1fa5/apps/playnite-web/src/server/data/types.entities.ts#L340) +[types.entities.ts:340](https://github.com/andrew-codes/playnite-web/blob/8e4fb0564dac8f04f0ec7b3de8bb1500c246dd52/apps/playnite-web/src/server/data/types.entities.ts#L340) diff --git a/docs/types.entities/variables/runStates.md b/docs/types.entities/variables/runStates.md index a4131301d..a533afd7c 100644 --- a/docs/types.entities/variables/runStates.md +++ b/docs/types.entities/variables/runStates.md @@ -12,4 +12,4 @@ Possible run state values. ## Defined in -[types.entities.ts:231](https://github.com/andrew-codes/playnite-web/blob/f4b196c836ff1f14161b4d04346bf7c194eb1fa5/apps/playnite-web/src/server/data/types.entities.ts#L231) +[types.entities.ts:231](https://github.com/andrew-codes/playnite-web/blob/8e4fb0564dac8f04f0ec7b3de8bb1500c246dd52/apps/playnite-web/src/server/data/types.entities.ts#L231)