Document --incremental and composite project APIs

[DanielRosenwasser]

Follow-up from #29978, suggested by @MLoughry at #29978 (comment)

[ToddThomson]

Thank-you for the new incremental APIs in the upcoming Typescript 3.6!

I've read through the code, but cannot yet see how to plug in my own "compiler" to the solution builder so that I can make my own call to emit. My call to emit is needed to pass in transformers to the build. I can see how the "Watch" compiler is used from the builder, but that is not quite what I need.

@sheetalkamat If you could direct me down the right path to save me a bit of time I would be appreciative. Thanks in advance!

Edit:

Using getNextInvalidatedProject() looks promising and/or emitNextAffectedFile...

[sheetalkamat]

@ToddThomson The provision already exists and as you found out, If you need to pass custom transformers etc for emit you need to call getNextInvalidatedProject to get next project to build to get the project. It can return project to update time stamps on or just update --out file or project that needs build. The emit in the later two types of project does take custom transformers.

[ToddThomson]

@sheetalkamat Thank-you. The use of getNextInvalidatedProject seems quite clear.

It was my assumption that overriding emitNextAffectedFile during host.createProgram would allow custom transformers to be introduced to the solution builder pipeline when using build(). This does not work, but I feel that it should. I'd be interested to know why.

[sheetalkamat]

That's because in build is for all the projects and its not clear if the transformers are suppose to be for one project or for all..

[ToddThomson]

@sheetalkamat That makes sense. Perhaps transformers should be part of the project configuration file then.

Thanks for your help and have a great day!

[hipstersmoothie]

@sheetalkamat I'm having trouble getting my custom compiler to actually use the buildInfo files to shorten the builds

      const host = ts.createIncrementalCompilerHost(allOptions, ts.sys);
      const program = ts.createIncrementalProgram({
        host,
        options: allOptions,
        projectReferences,
        rootNames: fileNames
      });

      const { diagnostics: emitDiagnostics } = program.emit();

my options look like

{ target: 1,
  module: 1,
  strict: true,
  jsx: 1,
  allowSyntheticDefaultImports: true,
  sourceMap: true,
  declaration: true,
  lib:
   [ 'lib.es2015.d.ts',
     'lib.es2017.d.ts',
     'lib.dom.d.ts',
     'lib.es2019.d.ts' ],
  esModuleInterop: true,
  experimentalDecorators: true,
  resolveJsonModule: true,
  downlevelIteration: true,
  outDir: 'dist',
  rootDir: '/Users/alisowski/Documents/cgds/components/Card/src',
  composite: true,
  configFilePath:
   '/Users/alisowski/Documents/cgds/components/Card/tsconfig.json',
  incremental: true,
  emitDeclarationOnly: true }

any guidance? when I run tsc with the same setup it uses the buildinfo files

[ulrichb]

@sheetalkamat I would also need some hint.

I tried this:

const host = ts.createIncrementalCompilerHost(compilerOptions);
const options: ts.CompilerOptions = {
    ...compilerOptions,
    incremental: true,
    tsBuildInfoFile: "tsBuildInfo.json"
};

const program = ts.createIncrementalProgram({ rootNames: filesToCompile, options, host });

let nextAffected;
while ((nextAffected = program.emitNextAffectedFile()) !== undefined) {
    const result = nextAffected.result;
    console.log(result.emitSkipped); // Always false :(
    console.log(result.diagnostics);
}

return [
    ...program.getOptionsDiagnostics(), ...program.getGlobalDiagnostics(), ...program.getSyntacticDiagnostics(),
    ...program.getDeclarationDiagnostics(), ...program.getSemanticDiagnostics(),
];

... and I also get a written tsBuildInfo.json, but it doesn't seem to be used on re-compilations: The "cold start" time is the same as without incremental compilation and result.emitSkipped is always false.

[sheetalkamat]

@sheetalkamat I'm having trouble getting my custom compiler to actually use the buildInfo files to shorten the builds
const host = ts.createIncrementalCompilerHost(allOptions, ts.sys);
const program = ts.createIncrementalProgram({
host,
options: allOptions,
projectReferences,
rootNames: fileNames
});

  const { diagnostics: emitDiagnostics } = program.emit();

my options look like
{ target: 1,
module: 1,
strict: true,
jsx: 1,
allowSyntheticDefaultImports: true,
sourceMap: true,
declaration: true,
lib:
[ 'lib.es2015.d.ts',
'lib.es2017.d.ts',
'lib.dom.d.ts',
'lib.es2019.d.ts' ],
esModuleInterop: true,
experimentalDecorators: true,
resolveJsonModule: true,
downlevelIteration: true,
outDir: 'dist',
rootDir: '/Users/alisowski/Documents/cgds/components/Card/src',
composite: true,
configFilePath:
'/Users/alisowski/Documents/cgds/components/Card/tsconfig.json',
incremental: true,
emitDeclarationOnly: true }
any guidance? when I run tsc with the same setup it uses the buildinfo files

I am not sure what could be going wrong.. Try debugging and see if tsbuildInfo that is being read. If it is check if version written there is same as ts.version and go from there?