Repository: TypeScript
Issue: Config option to compile *and* embed code from an external project or folder
Labels: Suggestion,Awaiting More Feedback

## Related to

#9875

## Search Terms

rootDirs

## Suggestion

Basically, `rootDirs` is *almost* what I want, but not quite. What I'm looking for is the ability to (1) take a TS file (or directory of TS files) that's outside my project, (2) pretend it's inside my project in a particular location, and (3) have the output reflect the pretend location instead of the actual location. External TS files should be compiled as if they were located at the pretend location (so they should obey the settings of the tsconfig nearest to their pretend location, not their actual location).

Potential configuration:

```json
{
    "compilerOptions": {
        "embedPaths": [
            { "src": "/some/path/outside/project", "dest": "some/path/inside/project" }
        ]
    }
}
```

The main difference between this and `rootDirs` is that the compiler would perform this step:
 
> A build step will copy the files in src to the same directory in the output.

A small difference between this and `rootDirs` would be that the config would be an array of path src-dest pairs rather than a flat array.

## Use Cases

The primary use case for this is to enable code reuse without the need for taking on the complexities involved in solutions like custom NPM packages, git submodules, symlinks, etc.

While `rootDirs` could definitely be used to support this scenario in simple cases, where it's not hard to shuffle a few files around as a post-build step, it's non-trivial to tap into the build pipelines of tools like Create React App, Gatsby, etc.

## Examples

Actual location of folders and files (folders in **bold**):

- **common**
    - business-logic.ts
    - utility-functions.ts
    - other-stuff.ts
- **back-end**
    - index.ts
    - tsconfig.json
- **front-end**
    - index.ts
    - tsconfig.json

Configuration:

```json
{
    "compilerOptions": {
        "embedPaths": [
            { "src": "../common/business-logic.ts", "dest": "/embedded/business-logic.ts" }
        ]
    }
}
```

"Pretend" location of folders and files (folders in **bold**):

- **back-end**
    - index.ts
    - **embedded**
        - business-logic.ts
    - tsconfig.json
- **front-end**
    - index.ts
    - **embedded**
        - business-logic.ts
    - tsconfig.json

Desired output:

- **back-end-output**
    - index.ts
    - **embedded**
        - business-logic.ts
- **front-end-output**
    - index.ts
    - **embedded**
        - business-logic.ts

## Checklist

My suggestion meets these guidelines:

* [x] This wouldn't be a breaking change in existing TypeScript/JavaScript code
* [x] This wouldn't change the runtime behavior of existing JavaScript code
* [x] This could be implemented without emitting different JS based on the types of the expressions
* [x] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
* [x] This feature would agree with the rest of [TypeScript's Design Goals](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals).

Re: non goal 4...

> Provide an end-to-end build pipeline. Instead, make the system extensible so that external tools can use the compiler for more complex build workflows.

I wouldn't consider my proposal an "end-to-end" build pipeline. It's just a feature that outputs files in an easily specified hierarchy. One could easily argue that rootDirs does the same thing, except that the hierarchy it outputs is opinionated rather than flexible.