Skip to content

Conversation

@diraneyya
Copy link

@diraneyya diraneyya commented Sep 20, 2025

Summary

This PR enhances Evidence's development experience and proxy support with several improvements to CLI options, configuration, and developer workflows.

Key changes

  • Proxy Support: Added EVIDENCE_ALLOWED_HOST and EVIDENCE_BASE_PATH environment variables to enable Evidence's dev server to run behind reverse proxies (e.g., code-server auto port forwarding proxy, and also while using Cloudflare tunnels, are now both possible).
  • HMR Control: Added --disable-hmr CLI option and disableHmr()/enableHmr() SDK functions mainly for disabling the auto building of sources by the dev server when so desired by the user. Another CLI option, --disable-watchers was also added which disables the watchers created by the CLI script itself.
  • Development by Linking Local Evidence Packages: Fixed Tailwind CSS content scanning issues when linking local Evidence packages for CLI development, which maintains full compatibility with published
    packages.
  • Documentation: Added a manual for linking local Evidence packages to an existing Evidence project (DEVELOP.md) and updated CONTRIBUTING.md with this alternative development workflow, useful when developing the CLI (as opposed to developing Evidence's components and framework code).

Checklist

  • For UI or styling changes, I have added a screenshot or gif showing before & after
  • I have added a changeset
  • I have added to the docs where applicable
  • I have added to the VS Code extension where applicable

archiewood and others added 9 commits February 24, 2025 09:30
Add relative paths to Tailwind content scanning to
support local Evidence package development using
the file: protocol.

Maintains full compatibility with published
packages. (according to Claude)
disabling the watchers for sources and queries
was not enough to prevent these from reloading
This allows me to use code-server's automatic port
forwarding proxy which serves the dev website at:
https://hostname/proxy/port by setting the env var
to '/proxy/port' and in case of using a cloudflare
tunnel, configuring the tunnel to use the same path
@diraneyya
Copy link
Author

diraneyya commented Sep 20, 2025

Example usage (from package.json):

"scripts": {
    "build": "evidence build",
    "build:strict": "evidence build:strict",
    "dev": "EVIDENCE_ALLOWED_HOST=evidence.orwa.tech EVIDENCE_BASE_PATH=/proxy/3710 evidence dev --debug --port 3710 --host 0.0.0.0 --disable-watchers sources --disable-hmr sources /",
    // ...
  },

From the CLI's dev --help output:

>> npx evidence dev --help

  Description
    launch the local evidence development environment

  Usage
    $ evidence dev [options]

  Options
    --disable-hmr         Disables hot-reloading of certain features [sources,queries]
    --disable-watchers    Disables watching certain directories [sources,queries]
    --debug               Enables verbose console logs
    -h, --help            Displays this message

Fixes dual-use preview function by directly opening
Evidence web app by the startServer function instead
of routing through markdown preview logic.
(which usually receives local file paths not web
 app URLs)
various issues related to how external urls are
generated were corrected, and the preview implentation
simplified. a few things became more robust though
much work is needed to make the extension truly
robust, especially in remote environments such
as code-server
@diraneyya diraneyya had a problem deploying to Approval required to run action on external PR September 23, 2025 11:18 — with GitHub Actions Failure
@diraneyya diraneyya had a problem deploying to Approval required to run action on external PR September 23, 2025 11:18 — with GitHub Actions Failure
@diraneyya diraneyya changed the title Feature: disable HMR/watchers in the CLI, with other useful development features Feature: Added support for remote workspaces including code-server from Coder Sep 23, 2025
@diraneyya
Copy link
Author

diraneyya commented Sep 23, 2025

This is a work in progress, what started as a simple attempt to just allow disabling the generation of sources has unfolded into a big job!

PR: vscode-extension highlights

  • Corrected the handling of app URI's (internal vs. external)
  • Fixed the preview feature
  • Made the detection of a running Evidence server, as well as terminal handling, more robust in remote working environment, also added support for tooling/version managers like asdf, nvm, etc.

Screenshot

evidence_PR_1 evidence_PR2

Pending Issue

I still cannot for the life of my figure out how to fix the breadcrumbs when using a base path via EVIDENCE_BASE_PATH

@diraneyya
Copy link
Author

I discovered that my frustration fixing the breadcrumbs had to do with Cloudflare's caching.

Someone might argue that this use of Cloudflare tunnels exposing a dev server is both insecure, and also trying to make these tunnels do something that they are not supposed to do. This is true, and I do have to pause to think about this.

I am open to a discussion about this when you the have the time in the coming weeks. But for the time being I consider this PR complete for your review.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants