diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 0000000..f59d067 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,41 @@ +// For format details, see https://aka.ms/devcontainer.json. +{ + "name": "haxtheweb/create Dev Container", + "image": "ghcr.io/haxtheweb/devcontainer-nodejs:latest", + // Compatibility with SELinux + "runArgs": ["--security-opt", "label=disable"], + + // Configure tool-specific properties. + "customizations": { + "vscode": { + "settings": {}, + "extensions": [ + "runem.lit-plugin", + "bierner.lit-html", + "deque-systems.vscode-axe-linter", + "ecmel.vscode-html-css", + "oliversturm.fix-json", + "yzhang.markdown-all-in-one", + "zdodson.dddignore" + ] + } + }, + + // Use 'portsAttributes' to set default properties for specific forwarded ports. + // More info: https://containers.dev/implementors/json_reference/#port-attributes + "portsAttributes": { + "3000": { + "label": "Express Port", + "onAutoForward": "silent" + }, + "8000": { + "label": "Web Component Port", + "onAutoForward": "silent" + } + }, + + "workspaceFolder": "/home/node/${localWorkspaceFolderBasename}", + "workspaceMount": "source=${localWorkspaceFolder},target=${containerWorkspaceFolder},type=bind,consistency=cached", + + "postCreateCommand": "bash .devcontainer/setup.sh" +} \ No newline at end of file diff --git a/.devcontainer/setup.sh b/.devcontainer/setup.sh new file mode 100644 index 0000000..597aa8c --- /dev/null +++ b/.devcontainer/setup.sh @@ -0,0 +1,7 @@ +#!/bin/bash +npm install +npm link + +printf "\033[34mhaxtheweb/create Next Steps:\033[0m\n" +printf "Run \033[34mnpm run dev\033[0m in one terminal window for live rebuilds\n" +printf "Open another terminal, then run \033[34mhax\033[0m to begin testing your work\n" \ No newline at end of file diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..c399a02 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,12 @@ +{ + "recommendations": [ + "bierner.lit-html", + "deque-systems.vscode-axe-linter", + "ecmel.vscode-html-css", + "oliversturm.fix-json", + "runem.lit-plugin", + "yzhang.markdown-all-in-one", + "zdodson.dddignore", + "ms-vscode-remote.remote-containers" + ] +} \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8f2f056..43c390f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,15 +24,44 @@ Reporting issues? Our unified issue queue is a good place for this: https://gith Need to discuss something via chat? Our [Discord can be joined here](https://bit.ly/hax-discord). ## Setting up a Development Environment -HAX has a built-in module for onboarding `hax party`! It'll get you up and running with tooling, repositories, and the community. - -### System dependencies +HAX provides several options to make onboarding accessible for new contributors. +1. Use our [Dev Container](https://containers.dev/) for a ready-made environment powered by Docker +2. Use the built-in `hax party` module to develop from your local device, leveraging your existing `haxtheweb/create` install + +Either way, we'll get you up and running with tooling, repositories, and the community. + +### Dev Container +* Install Docker (or another container runtime) + * [Windows](https://docs.docker.com/desktop/setup/install/windows-install/) + * Ensure that you select the **WSL 2 Backend** option + * Restart after install + * Certain Windows editions are bundled with an old WSL 2 version. If Docker Desktop warns that WSL 2 is outdated, please update through the [Windows Store](https://aka.ms/wslstorepage) or run `wsl --update` in **PowerShell**. + * [macOS](https://docs.docker.com/desktop/setup/install/mac-install/) + * [Linux](https://docs.docker.com/desktop/setup/install/linux/) + * [Dev Containers](https://containers.dev/) are broadly supported across OCI-compliant runtimes like Docker, Podman, and OrbStack. + +After this step you're ready to go! +1. Clone the project with [Git](https://git-scm.com/install/) or [GitHub Desktop](https://desktop.github.com/download/) +2. Select **Open in VS Code** +3. Select **Install Recommended Extensions** +4. Select **Reopen in Container**! + +### Local +#### System dependencies * [git](https://git-scm.com/) * [gh](https://cli.github.com/) (optional) * [yarn](https://yarnpkg.com/) `hax party` works great with just `git`, but contributors can get some extra convenience with GitHub's own `gh` utility. (You can fork repos directly from the CLI, rather than visiting the browser every time!) +#### Node.js configuration +For a local development environment, the official release of HAX may already be installed through `npm install -g @haxtheweb/create`. You'll need to give this project precedence over the global Node.js install. +* Run `npm link` in the root of the repository + +This overrides the global install, so that every `hax` command references your changes to the project. The typical workflow includes two terminal windows: +1. Run `npm run dev` in the first terminal to watch for changes, then rebuild +2. Use the second terminal interactively with `hax`, inspecting and testing your work + ## GitHub workflow We work primarily using pull requests and forks. In order to work most effectively, we ask that you FORK any project you are wanting to contribute to in our ecosystem. After taking a fork, submit a pull request while pointing to the associated issue tied to this pull request.