Local Setup Documentation

Ensuring an optimal local setup is crucial as it has a significant impact on developer productivity. The tools and guidelines provided from the outset are essential components in this process. A well-designed and reproducible local setup enables new developers to quickly acclimate and effectively troubleshoot any issues related to their machine.

Documentation Site

Using Structurizr is a valid approach, but hosting the website as an internal documentation site can be challenging. A more practical alternative is to create a static documentation site and host it via GitHub Pages. Nextra is a suitable choice for a static site generator. It offers a range of features that are beneficial for writing and reading technical documentation. You can compile your content into a static site and publish it on GitHub Pages. The source code is available here, and you can view the resulting site here.

Next.js Modifications

Part of setting up a machine usually involves copying various configuration files and commands. To make this easier, we have implemented code blocks with a copy function, allowing for easy copy-pasting during setup.

``` copy
brew install pnpm ```

With files, it is beneficial to have them available as actual files in git, as well as displaying their contents on the static documentation site. To achieve this, we can add the remark-code-import plugin to our list of MDX remark plugins. This plugin is only available as an ESM module, so we need to update our next.config.js to next.config.mjs, as described in the Next.js documentation. After this, files can be referenced in a code block and imported at compile time.

```yaml copy filename="override.yaml" file=local/override.yaml```

To configure the Next.js site for static hosting, we also need to disable image optimization, set the output to export, and update the basePath to reflect the static site’s base path.

Command Line Executions

There are numerous products available that aim to make a developer’s life easier, ranging from fully hosted online solutions to local installations of tool suites. Despite the convenience these products offer, I prefer to configure and run everything locally due to the associated costs and my need for specific customizations. I strive to create reproducible scripts to simplify the installation process, although organizing and structuring shell scripts can be challenging. Taskfile is a helpful tool in this context.

The Taskfile at the root of the repository points to a local folder where a nested Taskfile contains the commands for local setup. The steps are well-documented, and additional details are available in the Taskfile as shell commands. While it might be tempting to use a workflow tool for local setup, I believe that creating a process that can accommodate every possible issue and variation is not worth the effort.

Local environments evolve over time as new tools are discovered and integrated. Sometimes, a well-documented manual solution is quicker and more effective for project management.