fix(plugins): document project-root placeholder and correct DevboxDirRoot docs#2895
Open
mikeland73 wants to merge 2 commits into
Open
fix(plugins): document project-root placeholder and correct DevboxDirRoot docs#2895mikeland73 wants to merge 2 commits into
mikeland73 wants to merge 2 commits into
Conversation
… docs
The plugin docs described `{{ .DevboxDirRoot }}` as pointing to the project
root (where devbox.json lives), but it actually resolves to
`<projectDir>/devbox.d` — the shared parent of every plugin's DevboxDir. The
nginx, caddy and apache plugins all rely on this `<projectDir>/devbox.d`
meaning, so the implementation is correct and the documentation was wrong.
This left users (issue #1987) with no documented way to reference the project
root, even though a correctly-named `{{ .DevboxProjectDir }}` placeholder
already existed (used by the python, poetry and apacheHttpd plugins) but was
undocumented and only wired into one of the two template contexts.
- Expose `DevboxProjectDir` in the create-files template context too, so the
placeholder works consistently in generated file contents (it was already
available for env vars, init hooks and create_files keys).
- Correct the plugins README: document `{{ .DevboxProjectDir }}` as the project
root and fix the `{{ .DevboxDirRoot }}` description.
- Add a unit test pinning the meaning of each template placeholder.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UXuHTgPqNNZWowkgsh7Ydw
The previous run's test matrix was cancelled by fail-fast after the Nix experimental installer download returned HTTP 503 from artifacts.nixos.org, which is unrelated to the changes in this PR. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UXuHTgPqNNZWowkgsh7Ydw
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes #1987.
The plugin authoring docs describe
{{ .DevboxDirRoot }}as pointing to "the root folder of their project, where the user'sdevbox.jsonis stored." It does not — it resolves to<projectDir>/devbox.d, the shared parent directory of every plugin'sDevboxDir.This is what the reporter hit: putting
cd {{ .DevboxDirRoot }}in aninit_hookcds into<projectDir>/devbox.d(which may not even exist) instead of the project root.The implementation is actually correct — the built-in
nginx,caddy, andapacheHttpdplugins all rely on{{ .DevboxDirRoot }}meaning<projectDir>/devbox.d(e.g. nginx writes{{ .DevboxDirRoot }}/web/index.htmland serves from../../../devbox.d/web). Changing the semantics would break them and any user plugin relying on the current behavior. The documentation was simply wrong.A correctly-named placeholder for the project root already existed —
{{ .DevboxProjectDir }}, used by thepython,poetry, andapacheHttpdplugins — but it was undocumented and only wired into one of the two template contexts (buildConfig, which handles env vars / init hooks /create_fileskeys), not the create-files content context.Changes
internal/plugin/plugin.go: exposeDevboxProjectDirin the create-files template context as well, so the placeholder renders consistently in generated file contents (not just in env vars, init hooks, andcreate_fileskeys).plugins/README.md: document{{ .DevboxProjectDir }}as the project root, and correct the{{ .DevboxDirRoot }}description to<projectDir>/devbox.dwith a note that it is not the project root.internal/plugin/plugin_test.go: newTestBuildConfigTemplatePlaceholderspinning the meaning of each placeholder (DevboxProjectDir,DevboxDirRoot,DevboxDir,Virtenv) so this can't silently drift again.No behavior change for existing plugins —
DevboxDirRootkeeps its current value; this only documents reality and makes the existing project-root placeholder usable everywhere.How was it tested?
go test ./internal/plugin/— passes (including the new test).go build ./internal/plugin/andgo vet ./internal/plugin/— clean.gofmt -l— no diffs.Community Contribution License
All community contributions in this pull request are licensed to the project
maintainers under the terms of the
Apache 2 License.
By creating this pull request, I represent that I have the right to license the
contributions to the project maintainers under the Apache 2 License as stated in
the
Community Contribution License.
cc @mootoday (issue reporter)
🤖 Generated with Claude Code
Generated by Claude Code