`buildStep.writeAsString` within `PostProcessBuilder` does not produce any files

[Tienisto]

When writing a PostProcessBuilder, any calls to buildStep.writeAsString or buildStep.writeAsBytes succeed but no actual files are visible on the file system.

Builder:

PostProcessBuilder postBuilder(BuilderOptions options) {
  return PostBuilder();
}

class PostBuilder implements PostProcessBuilder {
  @override
  final inputExtensions = ['sample.txt'];

  @override
  Future<void> build(PostProcessBuildStep buildStep) async {
    print('Started PostBuilder...');

    final content = await buildStep.readInputAsString();

    final outputAssetId = AssetId(buildStep.inputId.package, 'lib/sample_upper.txt');
    final outputContent = content.toUpperCase();

    // Does not produce any file.
    await buildStep.writeAsString(
      outputAssetId,
      outputContent,
    );

    print('Written to $outputAssetId with content: $outputContent');

    buildStep.deletePrimaryInput();
  }
}

Logs:

2s compiling builders/jit                                                                                                                                                                                                                                                                                         
0s build_runner_test:normal_builder on 1 input: 1 output                                                                                                                                                                                                                                                          
                                                                                                                                                                                                                                                                                                                  
lib/$lib$ build_runner_test:normal_builder                                                                                                                                                                                                                                                                        
W Written to  build_runner_test|lib/sample.txt                                                                                                                                                                                                                                                                    
lib/sample.txt build_runner                                                                                                                                                                                                                                                                                       
W Started PostBuilder...                                                                                                                                                                                                                                                                                          
W Written to build_runner_test|lib/sample_upper.txt with content: HELLO WORLD                                                                                                                                                                                                                                     
                                                                                                                                                                                                                                                                                                                  
Built with build_runner/jit in 2s with warnings; wrote 2 outputs.

Setup:

Dart SDK version: 3.10.8 (stable) (Tue Jan 27 00:02:04 2026 -0800) on "macos_arm64"

Sample repository:
https://github.com/Tienisto/build_runner_test

[davidmorgan]

Thanks for reaching out.

That's because post process builders are always set to "hidden output", they produce output under .dart_tool/build instead of in the main source tree.

Historically this limitation was because build_runner wants to be compatible with bazel, which requires that all outputs be predeclared, i.e. builders are not allowed to decide at runtime what to output. But, I think it makes sense to support in some form, acknowledging that bazel is not particularly important to open source Dart use today :)

If you run build_runner with the output flag to produce a build output directory, then the post process output be will copied there alongside the input sources and the other build output. Apart from the annoyance of using the flag and the different location, does this do what you want?

If so I could look at supporting post process builders with non-hidden output, would be configured in build.yaml for the builder.

I think there's a different way to do this that will work today. You could run the build using a "placeholder" input instead of a glob input. $lib$ is a placeholder corresponding to the entire lib folder, so your builder will run once for every lib folder. You can specify one or more output files by exact name. For example here

build/build_web_compilers/build.yaml

Line 71 in 0627d11

build_extensions:

that might seem like not exactly what you want because you want to output one file per locale and I guess the locales are configurable. But actually you can fill this value at runtime and it's mostly the runtime value that is used

build/build_web_compilers/lib/src/dev_compiler_builder.dart

Line 88 in 0627d11

buildExtensions = {

--so at runtime you can compute which output files you need and return them there.

build/build_modules/lib/src/meta_module_builder.dart

Line 34 in 0627d11

r'$lib$': [metaModuleExtension(_platform)],

I'm not sure if there is any advantage to doing this vs the post process builder approach, I'd be interested to hear your opinion.

This is currently an under-documented and awkward part of build_runner, sorry about that. I'll be happy to improve it once we can figure out the right way to go.

[Tienisto]

Thanks for your insights!

The problem the i18n generator has is that

• the base locale always needs to be processed first (this is possible using your $lib$ trick)
• locales are known at runtime

To construct buildExtensions dynamically, I need to run buildStep.findAssets(pattern) which properly respects the --workspace flag. However, I don't have access to buildStep.findAssets when I want to construct buildExtensions dynamically.

Edit: So adding a flag to enable non-hidden outputs in build.yaml for the PostProcessBuilder would be the easiest solution right now

[davidmorgan]

Hmm, yes, that makes sense: actually buildExtensions can't work in that way for a multi package build, because the answer should be different for different packages in the workspace. Which is kind of how we got to this in the first place :)

Is PostProcessBuilder with non-hidden outputs a good fit for your use case, or would something else new be preferable?

For example I can imagine letting normal builders do something like

buildStep.writeUndeclaredAsString(assetId, content, {bool hidden = false, bool temporaryInternalFile = false});

which would write an output that is a lot like a post process builder output: it must not be the same as an input file or a normal build output, no other builders can see it, and it will be deleted on the next build if it's not output again.

You could set hidden to control whether it's written to .dart_cache or not. If you set temporaryInternalFile then it's deleted at the end of the build instead of (maybe) copied to the build output.

@rrousselGit @schultek @Markzipan I wonder if you have any thoughts on this one please :) ... I am considering ways to improve support for builders outputting undeclared files.

[Tienisto]

buildStep.writeUndeclaredAsString is even better for me. It avoids the hacky way to write to a temporary file that is not expected to be parsed by other builders only to be used by PostProcessBuilder

[Markzipan]

A buildStep.writeUndeclaredAsString would be immensely helpful for my use cases as well (both 'optional' and 'on-every-build'). In this case, I'm writing a 'summary' file that another tool ingests that must be regenerated on every rebuild.

[davidmorgan]

Thanks everyone!

The post process builder change is easier than writeUndeclared, so I'll do that first #4373

[davidmorgan]

@Tienisto with #4373 the strategy you were trying first should now work. If you'd like to try it before then you can use a git dependency, something like

dependencies:
  build_config:
    git:
      url: git@github.com:dart-lang/build.git
      ref: 03074eed8ce45e0225081f847e080757bfecf478
      path: build_config
  build_runner:
    git:
      url: git@github.com:dart-lang/build.git
      ref: 03074eed8ce45e0225081f847e080757bfecf478
      path: build_runner

not 100% sure when I'll release it but I guess within a week or two.

I'll leave this issue open for the writeUndeclared idea.

Thanks!

[davidmorgan]

Released the post process builder change in 2.12.0 @Tienisto please let me know if it works for you :)