nodejs-php-fallback/stylus
PHP wrapper that compiles Stylus stylesheets by falling back to the official Node.js compiler, with a simple API for turning .styl files into CSS. Useful for Laravel and other PHP projects that want the Stylus preprocessor without a native PHP port or extra build tooling.
Architecture fit. The package is a thin process-execution shim, not a framework component. It exposes Stylus (a Node.js CSS preprocessor) to PHP by shelling out to a local node/stylus binary and, when that is unavailable, falling back to a bundled pure-PHP Stylus parser. There is no service provider, no config publishing, and no Laravel coupling — which is good (nothing to fight) and bad (nothing to lean on). For a Laravel codebase it occupies the same slot as sass, lessphp, or a Vite/Tailwind pipeline: an asset-compilation step. It only earns its place if you have a meaningful body of existing .styl sources and a PHP-only runtime where Node cannot be guaranteed.
Integration feasibility. Composer-installable and MIT-licensed, so the mechanical integration is trivial: composer require nodejs-php-fallback/stylus, instantiate the compiler, point it at a source and target. Real feasibility is determined by two external preconditions: (1) Node plus the stylus npm package present on every environment that compiles assets, or (2) tolerance for the PHP fallback's output. Both are organizational commitments, not code changes.
Technical risk. High, concentrated in abandonment. Last release January 2019, 12 stars, zero dependents, overall score 0.09 — there is no maintainer, no CVE response path, no PHP 8.x/Node 18+ verification, and no community to answer questions. Secondary risks: the PHP fallback is a reimplementation and will drift from the Node reference implementation (selector ordering, @extend, color functions, vendor prefixing, source maps), producing environment-dependent CSS; exec/proc_open is frequently disabled on hardened hosts and behaves differently across Windows and Linux; and unsanitized paths passed to a shell command are an injection surface if any part of the path is user-influenced. Stylus itself is a low-activity ecosystem relative to Sass, so the upstream dependency is also a slow-moving liability.
Key questions. Do we actually have .styl sources, or is this being considered for greenfield styling? Is byte-identical output required across dev, CI, and production, or can fallback divergence be tolerated? Which PHP and Node versions must be supported, and who owns patching them? Is proc_open permitted on our production hosts? Can we vendor/fork the package under our own namespace and treat it as internal code? What is the migration target — Dart Sass or Laravel's default Vite pipeline — and how large is the rewrite?
Stack fit. Fits a Laravel app only as a compile-time dev/CI dependency, not a runtime service. Recommended posture: require it in require-dev, compile during build, ship static CSS. Use the Node path exclusively and treat the PHP fallback as unreachable code — a fallback that silently produces different CSS is worse than a hard failure.
Migration path. Before adopting, inventory .styl files and compile them once with the real Node toolchain to capture golden-output fixtures. Then choose: (a) migrate to Dart Sass or Vite in the same sprint if the stylesheet surface is small — this is the preferred path given the package's age; or (b) if Stylus must stay, vendor the package into the repo, pin stylus in package.json, and wrap it behind a single internal StylusCompiler interface so the dependency is swappable later. The interface boundary is the actual deliverable; the package is replaceable behind it.
Compatibility. Verify against your current PHP (8.1+) and Node LTS explicitly — the 2019 release predates both. Expect to patch deprecations yourself. Pin the npm stylus version rather than floating, and pin the Composer constraint to an exact version, since no future releases are coming.
Sequencing.
Maintenance. Effectively unmaintained upstream; all maintenance transfers to you on day one. Budget for a fork, a CI matrix (PHP × Node LTS), and periodic npm advisory triage on the pinned stylus package that no one else will do for you. This is a small codebase (low absolute cost) with a high per-line ownership burden (no upstream to defer to).
Support. No maintainer, no issue triage, no Stack Overflow corpus. Internal documentation must cover the compiler invocation, Node prerequisite, and the decision record explaining why Stylus exists here. Ramp-up for a new engineer is low in code volume but high in archaeology: they will need to understand both the wrapper and the preprocessor.
Scaling. Compilation is per-file subprocess spawn — CPU-bound and costly if run per-request. Never compile in the request path; precompile at build/deploy. At scale, artifact caching and a deterministic build environment matter more than the tool itself. Horizontal scaling is unaffected once assets are static.
Failure modes.
node or stylus missing on a host → silent fallback to PHP → divergent CSS in production. Mitigate by failing loudly and disabling fallback.proc_open/exec disabled by host policy → hard failure on deploy.Ramp-up. Half a day for a mid-level engineer to use the API; one to two days to make it production-safe (fork, pin, CI, sanitize, fixtures). The dominant cost is the follow-on migration decision, not the integration. Recommendation: treat this as a stop-gap. Approve only with a named owner, a vendored fork, fallback disabled, and a committed date to move to Dart Sass or Vite.
How can I help you explore Laravel packages today?