Remove browser.d.ts

[basarat]

⚠️ Update for new readers

Typings 1.x no longer creates browser.d.ts (only index.d.ts which is same module resolution pattern as the old main.d.ts). This decreases the setup time for new devs.

More on where do typings install : https://github.com/typings/typings/blob/master/docs/faq.md#where-do-the-type-definitions-install 🌹

---

Original issue report

Would like to discuss if we truly need browser.d.ts and main.d.ts. Would like to table the desire to remove browser.d.ts at least for the time being.

With the default tsconfig, Something like {}:

• The user will get a lot of duplicate identifier errors.
• The user needs to go ahead and do one of the following:
  • exclude: ["typings/browser", "typings/browser.d.ts"] < not intutive to a newbie
  • OR exclude: ["typings/main", "typings/main.d.ts"] < not intutive to a newbie

General issues

• Everytime there is a typings install it will overwrite browser.d.ts / main.d.ts anyways and that puts them back in step one.
• It is unclear how the user would organize his codebase to effectively use main and browser side-by-side. And for the user that does manage that they can probably generate the browser.d.ts and main.d.ts themselves.

I just had a colleague go through and start a new TypeScript project and they struggled till I was brought in 🌹

[unional]

How about adding env in typings.json so that only one of browser.d.ts and main.d.ts will be generated? Is there a need to use both of them in the consuming project?

Maybe server side code uses main.d.ts and browser side code uses browser.d.ts? Don't know how would the IDE support that scenario. 🌹

[PatrickJS]

I would argue to allow more types (webworker) but I'm okay with not making it a default. For my use case, it's Universal JavaScript (in particular case Angular 2 where we run Angular 2 on the server/client/webworker). I'm totally fine with a flag or, at least, options in typings.json.

[oliverjanik]

I just tried Typings because tsd says it's deprecated. And it is not a drop in replacement. I'm getting ton of duplicate errors now.

How do I resolve that for good? So that if I do a clean checkout I can easily just do typings install and get going?

How is this even intented to be used? Unless I have each *.ts file specified in tsconfig individually this will break for everyone almost immediately. How is this a sane default?

This issue needs to be escalated.

[unional]

@oliverjanik
If you use files in tsconfig.json, then just include either typings/main.d.ts or typings/browser.d.ts.
If you use exclude, then exclude typings/browser and typings/browser.d.ts if you use main, or vice versa.

[basarat]

@unional thanks! I've updated the original question to point out that one needs to exlcude just typings/main or typings/browser and not use reference tag (I knew I was doing something wrong). Also I've added another issue about the fact that having these two doesn't solve the complete workflow for the user anyways and just increases the initial friction 🌹

Nevertheless great work everyone. Thanks for trying to make the world a better place ❤️ 🌹

[unional]

@basarat you are welcome. You are making the world a better place just by giving out bunch of 🌹 🌹 😄

[oliverjanik]

Works, cheers. Maybe put this into intro docs?

[blakeembrey]

@oliverjanik Like https://github.com/typings/typings#maindts-and-browserdts?

@basarat Browser is the tree generated by following browser resolution (see https://github.com/defunctzombie/package-browser-field-spec). It's not possible to create this easily yourself, hence Typings is currently generating it. 99% of the time, these files are likely the same and I agree it's confusing. The issue is that 1% extra that may need the browser typings that are a tiny bit different to the node version, and TypeScript does not support this using native module resolution.

Anyway, I can understand the friction issue, it's just there's not a good solution. For most users, it's a quick exclude or add one entry to files. For the reverse support, however, it's incredibly painful.

To see how one might use this, I've open sourced this little app I wrote for a presentation last week: https://github.com/blakeembrey/hello-world-app. See https://github.com/blakeembrey/hello-world-app/blob/master/app/tsconfig.json#L13 (front-end) and https://github.com/blakeembrey/hello-world-app/blob/master/src/tsconfig.json#L13 (back-end).

[oliverjanik]

No, like this:

    "exclude": [
        "node_modules",
        "typings/main.d.ts",
        "typings/main"
    ]

[blakeembrey]

There's a note that says to do that? I don't think I can write every combination of exclude that would be used. Did you see:

Please note: If you're relying on "exclude" behavior instead, you can exclude typings/browser.d.ts and typings/browser (replace browser with main, if you desire).

[oliverjanik]

I know, but I think it's not prominent enough. I believe this should be part of quickstart.

[blakeembrey]

Sure, me too. If someone wants to contribute quick start docs, that would be great.

[basarat]

I sent a PR. You can read it here https://github.com/typings/typings/tree/memo/browser#maindts-and-browserdts 🌹

[dsebastien]

Personally, I like the idea of an 'env' or 'envs' setting in typings.json where one could choose the "kind" of typings to include in a project. For example:

...
"envs": [
    "browser",
]

The behavior could be as follows:

• if key not present: default behavior
• if key is present, only generate the specified one(s) (at least one entry mandatory)

typings init could also directly add the key with the default env(s) defined.

I would argue that browser should be the default as there will probably be (at least for a while) proportionally more developers using TS to create Web applications (due to the influence of Angular 2).

[unional]

@basarat thank you for your example. 👍

[CaselIT]

Just switched from tsd to typings and I had to add the exclude line to avoid duplicate errors
I agree with #151 (comment) and #151 (comment) env or similar inside typings.json would be useful to avoid the issue.

[basarat]

For everyone the issue is closed as https://github.com/typings/typings/tree/master#maindts-and-browserdts should be clear. As blake said having the user create browser.d.ts is non trivial so I understand why it needs to be done by default. I've also made the default tsconfig.json generated by atom-typescript put in the proper exclude for you 🌹

Feel free to PR more docs 🌹

[joe-herman]

I do not think this issue should be closed.

EDIT: See #151 (comment)

While instructions were provided on how to manually select between browser.d.ts or the main.d.ts, there should be a default of one or the other, or at the very least a programmatic way of setting this option instead of manually ignoring half the files that get generated.

Creating a Typescript project should not yield tons of duplicate identifier errors (I created a new project using TS 1.7.5, added some typings, a basic Hello World file, and ran tsc). The Typescript community should not have to resort to workarounds just to use Typescript.

@blakeembrey, you said it yourself:

99% of the time, these files are likely the same and I agree it's confusing. ... The issue is that 1% extra that may need the browser typings that are a tiny bit different to the node version, and TypeScript does not support this using native module resolution.

So why clutter 99% of people's repos with duplicate typings?

I propose any or all of following:

1) Create a typings.json member that enables browser.d.ts and the /browser folder structure. Maybe just browser as a boolean. Alternatively, maybe env: #151 (comment)

2a) Create a commandline option (perhaps typings --browser [value]) that sets this browser or env value in typings.json programmatically, and fetches/installs typings accordingly, because users should never have to touch typings.json manually unless they want to do something out of the ordinary.

2b) Alternatively, this commandline option could modify tsconfig.json instead, adding or removing browser.d.ts or main.d.ts from the ignore section.

3) By default, use only main.d.ts, and keep the current folder structure it already creates.

The goal is to add typings using only the project's commandline and have it work out of the box. And then if people need browser typings, they can add them too.

Criticism, suggestions, and improvements welcome.

[blakeembrey]

The Typescript community should not have to resort to workarounds just to use Typescript.

You would also need to exclude things like node_modules too, it's a similar concept here.

So why clutter 99% of people's repos with duplicate typings?

Because there's not a cleanly proposed alternative.

1. This one is pretty reasonable, the only issue is that it conflicts with the existing browser field override. Maybe browserResolution. But then peoples that enable that might complain about having main lying around still. And personally, I need both. The usage of env is not correct, even the comments here were confused by what it actually was meant to do since it's not an environment and more a resolution tweak.
2. I'm happy with implementing something that tweaks tsconfig.json, but it doesn't fix the issue - you would still be in the same situation unless you knew to run the command. Also, what's the command specifically do and where does one find tsconfig.json?
3. What if a user needs both?

Anyway, I'm sure I brought these points up already, but I'm happy to solve it properly once we have a good solution for solving it.

[blakeembrey]

Also, who is the most common user in this use-case? Do browserify + webpack + etc. users want accurate typings from the get go without tweaks? It may be possible to remove duplicate identifiers when the content is the same, hence removing the issues for the majority until one type definition is actually different - would that help or just push the issue down the road?

[blakeembrey]

Ok, this probably won't happen for a long while, but perhaps a map with enabled additional resolutions?

{
  "resolution": {
    "browser": true
  }
}

Maybe some others appear later. In this case, we'll always generate main but also add browser.d.ts later. The only tricky part of this is making sure the typings/ directly ends up staying in sync with changes.

[joe-herman]

You would also need to exclude things like node_modules too, it's a similar concept here.

I didn't have to when creating a test project actually. Historically I have had to ignore node_modules in tsconfig.json though.

Because there's not a cleanly proposed alternative.

Fair enough.

Maybe browserResolution. But then peoples that enable that might complain about having main lying around still. And personally, I need both.

I see. Just for my own understanding, in order to use both, you'd need to compile each subproject separately and include browser.d.ts and main.d.ts, right? I see in your example here you have one set of typings for two parts of your project, and separate tsconfig.json files to match.

I did not fully understand the problem before, since I've only worked with projects that had a single tsconfig.json. I now see why you have created separate browser and main typings. And unfortunately, I think we now have a bigger problem at hand.

Disclaimer:
With all due respect to your example project and work done to make the separate main and browser feature, I'm about to criticize it as politely as I can. I'm not trying to be mean, but I think we all understand the gravity of this Typings project and what it means for the future of Typescript, and it's important we align it with the Typescript team's vision.

I think with separate main and browser typings you have created a decent solution to your own problem that should not exist in the first place.

Referring to the opening line of https://github.com/Microsoft/TypeScript/wiki/tsconfig.json

The presence of a tsconfig.json file in a directory indicates that the directory is the root of a TypeScript project.

To me, this means the /typings directory and typings.json belong in the same directory as tsconfig.json. You have instead structured it such that each subproject has its own tsconfig.json and therefore should have its own /typings.json. Your typings are now one level up from where they should be.

But now you have two projects that rely on the same typings, but different versions of them (browser and normal). Your solution was to create browser and main, but to me, the solution should have been to maintain two typings.json files (one per tsconfig.json) in your subproject directories. Yes, maintaining two things is less clean, but we are really talking about two Typescript projects that you have bundled into one.

Basically, in solving your project structure problem, you have created a new one for everyone else.

In light of the above, I think the solution to this problem will involve:

1. A single /typings directory, much like TSD. No main or browser subdirectory, just /typings/node/node.d.ts for example.

2. Enforcing the concept that only one type of /typings exists, by way of a variable in typings.config, so your typings may either be browser or main (maybe down the line, another use case or version for Typescript will emerge, and some other type of typing will be necessary). I vote to make this a string.

3. Some commandline way of setting 2.

Again, I'm really sorry to rip into this. This is the strongest I've felt about something codewise. I'm going to strikethrough my previous suggestions.

Discussion encouraged, because to me this is a massive breaking change.

[blakeembrey]

Your typings are now one level up from where they should be.

This is certainly reasonable, I don't take any of it personally (yet). Anyway, it depends on what angle you look at it, but you're somewhat right. I'll see what I can do for next release to change the structure. The way I saw Typings is that you're typings JavaScript projects, so it should mirror package.json more than compiler options (even tsconfig.json has "non-root" issues, such as the module resolution resolving outside of the root too).

Basically, in solving your project structure problem

I don't think it's a project structure problem, the project is structure correctly. Maybe you could separate package.json into two directories too, which would improve that. The issue is that I've tried to "polyfill" a module resolution that TypeScript doesn't understand itself and then provided both assuming people understood how "files" or "excludes" worked. That may have been a mistake now, but not impossible to change.

For 1, we can't do directly that but we can move typings/main up one directory. Ambient and non-ambient still need to be separated.

For 2, agreed. I suggest resolution: browser or something similar.

For 3, not sure - maybe just a flag during init. Again, I guess I treat typings.json more canonical to package.json though.

Anyway, some things to keep into account here too. In the future, TypeScript can have multiple tsconfig.json files. It's no longer a perfect standard root and you could have two configs alongside each other. This allows people to move those two files I have and put them alongside each other. Additionally, a semi-related thought, perhaps we want to consider overriding the output directory (it's been requested) and that can also be factored into this somehow?

All in all, I'll see what I can do for 0.7 but please continue the discussion.

[joe-herman]

The way I saw Typings is that you're typings JavaScript projects, so it should mirror package.json more than compiler options (even tsconfig.json has "non-root" issues, such as the module resolution resolving outside of the root too).
...
The issue is that I've tried to "polyfill" a module resolution that TypeScript doesn't understand itself understand itself and then provided both assuming people understood how "files" or "excludes" worked.

Your logic makes sense, and the polyfill solution works. TS obviously can operate using a solution like the one you've made, but for the sake of being a strong partner to TS, I think Typings should aim to be installed alongside a TS root directory (which may or may not be the same as a project root directory).

For 1, we can't do directly that but we can move typings/main up one directory. Ambient and non-ambient still need to be separated.

That's a good point. I am mainly trying to avoid duplicate definitions.

For 2, agreed. I suggest resolution: browser or something similar.

For 3, not sure - maybe just a flag during init. maybe just a flag during init

Sounds perfect to me.

In the future, TypeScript can have multiple tsconfig.json files. It's no longer a perfect standard root and you could have two configs alongside each other.

We can still accommodate this by allowing separate /typings alongside each tsconfig.json, since the main idea is to avoid duplicate typings in the same folder.

Another solution could be to suggest better duplicate typings handling to the TS team, but I'm unsure how they'd accomplish that, and obviously the Typings project should focus on the present and near future features.

Additionally, a semi-related thought, perhaps we want to consider overriding the output directory (it's been requested) and that can also be factored into this somehow?

I have no opinion on this, but it sounds like a nice idea.

[blakeembrey]

What harm is having a 'both' option?

Only that it doesn't logically map with the rest of the feature. Logically, it's resolution: <resolutionName>. Logically everything in resolution: [x] is also valid in { [x]: <path> }.

Edit: To be clear, it's to minimise explicit documentation and surprises. The less surprising the behaviour, the better. If both were implemented, theoretically it should be possible to map it to a path also. But how's that interact now since it's consistent output (e.g. nesting is different on both vs just main or browser)?

[ghost]

If the 'both' option is removed, then typings wont behave as it does today, which I believe was extremely important to you. I mean, the PR can be left as is, and we just wont tell anyone there's a 'both' option, but you can still use it.

[blakeembrey]

@phestermcs I'm good with killing "both", we just need to make sure that both outputs are still possible (independently is fine, until we extend support for the object extension proposal). The reason is, the correct implementation without both still changes the structure which is a breaking change. So we can release 1.0 with out: [main | browser], then 1.1 with out { [main | browser]: [path] }. That's fine, we're just adding to an existing feature and not breaking anyone at that point.

[ghost]

Well, I'm a little confused. Arent there projects right now that depend on both browser and main being created, like some of yours? Of the 'both' option is removed, then what happens to you and others who are currently relying on both being output?

I honestly dont see what's logically or conceptually wrong with having a 'both' option, even when a later enhancement is made. I really really believed you when you said there are cases that require this today.

I think you should allow 'both'. But to confirm..

1. I'll change "resolution" to "out".
2. The default will be to create just the 'main' out if "resolution" is not configured, but with identical stucture as today
3. I'll remove the 'both' option

yes?

[blakeembrey]

Arent there projects right now that depend on both browser and main being created, like some of yours? Of the 'both' option is removed, then what happens to you and others who are currently relying on both being output?

Relying on it a tiny bit, but as we decided - it's an edge-case. Either way, those projects can stay on 0.8 a couple of extra weeks (this is the reason why it's fine, doing the object enhancement on top of a solid base should be easy).

with identical stucture as today

I want to kill the current structure, because it doesn't scale when we start configuring paths/output resolutions. It'd be good to use the structure I mentioned above.

Edit: Link to structure: #151 (comment).

[ghost]

I accept it would be good and nice to improve the 'default' structure, but can't that be part of your more 'complete' implementation?

Here's thing to please consider. The PR, right now, WORKS. Can't you just 'pretend' there was an explicit object specification with { "out": { "main" : "typings/main" } } ??? I mean, if when that feature is enabled, and I were to set it to that path, would I be doing something wrong?

Here's the thing, the more change, the more chance to break something, and fiddling with the directory 'default' structure isn't going to make the PR work any better or worse.

[blakeembrey]

@phestermcs The tests are failing on the PR, and you I'm guessing you haven't tested the uninstall feature as I mentioned, because there should be a warning if the file is not there when you try to delete (emitted https://github.com/typings/core/blob/master/src/utils/fs.ts#L71).

[ghost]

So. In Travis the tests failed on Node 0.10 and 0.12, but all tests passed for for later Node version.
In AppVeyor, all tests passed.

I did test all the commands, including uninstall. But you're saying that if the typing isn't there on uninstall the user should be told that?

To confirm changes to PR:

1. Change "resolution" to "out".
2. The default will be to create just the 'main' out if "resolution" is not configured, but with identical stucture as today
3. I'll remove the 'both' option
4. Ensure uninstall warns user if trying to uninstall a noexistent typings

yes?

[ghost]

So, uninstall is actually working correctly, in that it notifies if typings not there. However, the test is wrong now, as it's assuming two messages, rather than just one.

There is no uninstall.spec.ts... What actually is failing?

[blakeembrey]

The default will be to create just the 'main' out if "resolution" is not configured, but with identical stucture as today

If you don't want to do the full PR, feel free to say so. I know it's a bit of work when you're unfamiliar with a project, and it touches a decent amount of the project. I can try to make it happen this weekend or next week.

So, uninstall is actually working correctly, in that it notifies if typings not there.

Won't it notify that it can't find the browser version when you never installed the browser version with this addition?

There is no uninstall.spec.ts... What actually is failing?

Look at install.spec.ts. I'd guess you're rimrafing something before it's there with your PR?

[ghost]

If you don't want to do the full PR, feel free to say so. I know it's a bit of work when you're unfamiliar with a project, and it touches a decent amount of the project. I can try to make it happen this weekend or next week.

Ok, I dont recall ever saying I didn't want to do a 'full PR'. So what are you referring to? Are you saying you require new functionality to change the directory structure to be added in order for you to accept a minor change to resolve the pain? I'm feeling most of my 'work' is getting you to compromise as to what is a must-have vs. a nice-to-have.

Won't it notify that it can't find the browser version when you never installed the browser version with this addition?

There is only one failing test, it only happens on node 0.12. A failure is occurring on node 0.10 but there's some problem in that Travis goes into an infinite scroll when trying to view the test results for 0.10. The failure is not related to uninstall command, rather:

install dependency
✖ Error: ENOENT, unlink '/home/travis/build/typings/core/src/test/install-dependency-fixture/typings/browser.d.ts' at undefined
{ [Error: ENOENT, unlink '/home/travis/build/typings/core/src/test/install-dependency-fixture/typings/browser.d.ts'] errno: -2, code: 'ENOENT', path: '/home/travis/build/typings/core/src/test/install-dependency-fixture/typings/browser.d.ts' }undefined

Look at install.spec.ts. I'd guess you're rimrafing something before it's there with your PR?

No, functionally everythings working, it's a single test in node 0.12 that is not working. Further, because you want the 'both' option removed, I can no longer have the existing tests pass, and the all must be changed.

Here's what I'd like:

1. Change "resolution" to "out"
2. Leave the 'both' option in so tests and current behavior remain functioning
3. Leave the default directory structure in place. This will have NO IMPACT when the structure is set explicitly in your future enhancement, as the default and the explicit are mutually exclusive, and the default is as it is today which is clearly working JUST FINE.

So, how much money do you need to bend a little here?

[blakeembrey]

I don't follow, sorry. Wasn't the initial making resolution: main the default already a breaking change? Unless you plan to make out: both the default option, it's breaking as it is. Then I would be releasing another breaking change next week when I implement it correctly.

[blakeembrey]

Ok, I dont recall ever saying I didn't want to do a 'full PR'. So what are you referring to?

I only said it because you keep changing my statement about the directory structure. I said both times you asked it should be changed to implement the feature correctly.

[ghost]

Yes, changing the default to only output 'main' rather than 'both' would be a breaking change. But of your own admission:

Relying on it a tiny bit, but as we decided - it's an edge-case. Either way, those projects can stay on 0.8 a couple of extra weeks (this is the reason why it's fine, doing the object enhancement on top of a solid base should be easy).

So yes, it's a breaking change for you. But its a FIXING CHANGE for everyone else.

I only said it because you keep changing my statement about the directory structure. I said both times you asked it should be changed to implement the feature correctly.

I see, so even today, even though people are using typings with the current directory structure, even though my PR leaves that intact, even though that works just fine, even though a future enhancement allowing an explicit structure the would be mutually exclusive from the default being applied, even though if in that future the structure was explicitly set to what is default now and would still work just fine.... this is all 'incorrect'???? and in order to FIX A PAIN, you require this PR change the structure for your opinion as to a 'correct' structure even though you want to implement a future feature that lets user have what ever structure they want, including what the default is today, you wont accept this PR???

goodbye

[blakeembrey]

@phestermcs Just make both the default until we can roll the breaking changes together.

Edit: You seemed to miss the fact that I'm not avoiding your PR, I'm trying to do one breaking change instead of two.

[steve-perkins]

Apologies, but I've gotten a bit lost in this thread. I am one of the (apparently unusual) people who DO need to use both main.d.ts and browser.d.ts within the same project. I'm writing a desktop app with Electron... and the main process script requires only the former, while the renderer process requires only the latter.

I'll be interested to see where things ultimately land, after PR's are merged and future releases come out. But for the present, can someone please provide some guidance (or an example) for creating a project structure that allows different TypeScript files to employ different definitions?

I've experimented with creating separate subdirectories (./main/ and ./renderer/) for the two categories of source, with a tsconfig.json at the root and separate tsconfig.json's in each subdirectory. However, I have not yet had any success at forcing the separate subdirectories to include or exclude the appropriate typings.

[blakeembrey]

@steve-perkins I just released 1.0, it may become a little easier for you because you do something like:

{
  "resolution": {
    "main": "main/typings",
    "browser": "renderer/typings"
  }
}

[cebor]

i don't have read all the posts above:

but is it possible with the following configuration to use only browser?

{
  "resolution": "browser"
}

think its much simpler, i case you want to use the default paths

[blakeembrey]

@cebor No. You can't, because obviously it's obscure whether that string is a path or a resolution. Do:

{
  "resolution": {
    "browser": "typings"
  }
}

[bcherny]

1.x fixed it for me - thanks @blakeembrey

[carlpaten]

@basarat would you mind editing the OP to mention that this is fixed in 1.x? I literally read this entire conversation before I found the fix :(

[basarat]

@LilRed done 🌹

[rtm]

For a complete newbie to typings just trying to get some unit tests for an ionic project running, what is the final solution to the following error?

23 06 2016 16:00:40.600:ERROR [framework.browserify]: TypeScript error: app/app.e2e.ts(4,5): Error TS2304: Cannot find name 'browser'.

[blakeembrey]

For help, you should probably open an issue. That error isn't related to the larger issue. It's a TypeScript issue saying that a name (variable) named browser is not set when you've tried to use it.