denoland/deno · error · anyhow::Error

Cannot use --declaration without --output or --outdir. Decla

Error message

Cannot use --declaration without --output or --outdir. Declaration files must be written to disk.

What it means

Declaration (.d.ts) files are separate on-disk artifacts; they cannot be streamed to stdout alongside the transpiled JavaScript. `--declaration` is therefore rejected when neither `--output` nor `--outdir` is set.

Source

Thrown at cli/tools/transpile.rs:46

  transpile_flags: TranspileFlags,
) -> Result<(), AnyError> {
  let files = &transpile_flags.files;

  if files.is_empty() {
    anyhow::bail!("No input files specified");
  }

  if files.len() > 1 && transpile_flags.output.is_some() {
    anyhow::bail!(
      "Cannot use --output with multiple input files. Use --outdir instead."
    );
  }

  if transpile_flags.declaration
    && transpile_flags.output.is_none()
    && transpile_flags.output_dir.is_none()
  {
    anyhow::bail!(
      "Cannot use --declaration without --output or --outdir. Declaration files must be written to disk."
    );
  }

  let is_stdout_mode = files.len() == 1
    && transpile_flags.output.is_none()
    && transpile_flags.output_dir.is_none();

  if is_stdout_mode
    && matches!(transpile_flags.source_map, SourceMapMode::Separate)
  {
    anyhow::bail!(
      "Cannot use --source-map separate when outputting to stdout. Use --output or --outdir, or use --source-map inline instead."
    );
  }

  let factory = CliFactory::from_flags(flags.clone());
  let cli_options = factory.cli_options()?;

View on GitHub (pinned to 89f33cbef2)

Solutions

Add --outdir (usual case): `deno transpile mod.ts --declaration --outdir dist`
Or add --output for a single file: `deno transpile mod.ts --declaration -o dist/mod.js`
Or drop --declaration if only the emitted JavaScript is needed

Example fix

# before
deno transpile mod.ts --declaration > out.js
# after
deno transpile mod.ts --declaration --outdir dist

Defensive patterns

Strategy: validation

Validate before calling

# bash: require an output target whenever declarations are on
outdir="${OUTDIR:-dist}"
[ -n "$outdir" ] && deno transpile "$@" --declaration --outdir "$outdir"

Prevention

Remember declarations are files, not stdout content — always pair --declaration with --outdir or --output
In pipelines that capture stdout, never add --declaration without redirecting output to disk
Codify the flag pairing in a npm/script alias so it cannot be half-specified

When it happens

Trigger: `deno transpile mod.ts --declaration` with no `--output`/`-o` and no `--outdir`.

Common situations: Assuming declarations print to stdout the way transpiled JS does in single-file mode; pipelines that transpile to stdout and later gain a --declaration flag.

Related errors

AI-assisted analysis of denoland/deno@89f33cbef2 (2026-08-16). Data as JSON: /api/errors/1831a358e3bb12c5. Report an issue: GitHub.