Stylus 0.54: Recovering from a Failed Upgrade Due to Missing Import Errors

Immediate Fix for a Failed Upgrade

When stylus 0.54 throws a Missing file error, the build can be restored by temporarily installing a fallback importer that returns null for unresolved paths. This keeps the compiler happy while you audit the source.

// customImporter.js
module.exports = function (file, prev, done) {
  try {
    return { path: file, contents: require('fs').readFileSync(file, 'utf8') };
  } catch (e) {
    console.warn('Stylus missing import:', file);
    return null; // allow compilation to continue
  }
};

Run the compiler locally:

stylus -u customImporter.js src/main.styl -o dist

If the build succeeds, you have a working snapshot that can be committed while you investigate the missing files.

Detecting and Fixing Circular Imports

0.54 treats any circular import as an error. To pre‑empt this, build a dependency graph before the actual compile:

const stylus = require('stylus');
const fs = require('fs');
const path = require('path');

function buildGraph(entry) {
  const graph = new Map();
  function walk(file) {
    if (graph.has(file)) return;
    const content = fs.readFileSync(file, 'utf8');
    const imports = content.match(/@import\s+['\"]([^'\"]+)['\"]/g) || [];
    const deps = imports.map(im => path.resolve(path.dirname(file), im.replace(/\\.styl$/, '') + '.styl'));
    graph.set(file, deps);
    deps.forEach(walk);
  }
  walk(entry);
  return graph;
}

function detectCycles(graph) {
  const visited = new Set();
  const stack = new Set();
  const cycles = [];

  function dfs(node) {
    if (stack.has(node)) {
      cycles.push([...stack, node]);
      return;
    }
    if (visited.has(node)) return;
    visited.add(node);
    stack.add(node);
    const deps = graph.get(node) || [];
    deps.forEach(dfs);
    stack.delete(node);
  }

  graph.forEach((_, node) => dfs(node));
  return cycles;
}

const graph = buildGraph('src/main.styl');
const cycles = detectCycles(graph);
if (cycles.length) {
  console.error('Circular import detected:', cycles);
  process.exit(1);
}

Run this script in CI before the Stylus step. If any cycles are reported, refactor the involved files to remove the cycle (e.g., merge the modules or use mixin exports instead of imports).

Maintaining Build Stability in a Large Project

• Stage 1 – Validation: Add the graph‑building script to a pre‑build job that fails on missing files or cycles. Commit the results to a temporary branch.
• Stage 2 – Incremental Migration: Keep the fallback importer in the local dev environment only. In CI, run Stylus with the strict importer (no fallback) to catch any new missing imports introduced by code changes.
• Stage 3 – Production Build: Once the graph shows no cycles and the missing‑file list is empty, remove the fallback importer and enable stylus --strict in the final build step.
• Continuous Monitoring: Hook the graph script into nightly or pre‑merge checks so that any new import is validated immediately.

What If You Use Glob Imports?

Since @require no longer supports glob patterns, any plugin that expands them will still trigger missing‑file errors unless updated. If you rely on such a plugin, please confirm its current version and whether it handles missing files gracefully; otherwise, consider replacing it with explicit @import statements or a custom importer that expands globs before passing them to Stylus.

Safe Commands for Verification

• stylus -u customImporter.js src/main.styl -o dist – compile locally with fallback.
• node validateGraph.js – run the pre‑build validation script.
• stylus --strict src/main.styl -o dist – final build step that fails on any error.

Summary

By temporarily suppressing missing‑file errors, pre‑building a dependency graph to catch cycles, and then tightening the build pipeline, you can recover from a 0.54 upgrade and preserve stability across a large codebase. Remember to remove any silent‑import fallbacks before merging into production.