Configuring Aurelia

[EisenbergEffect]

The Aurelia team has been doing a lot of work to make our d.ts support follow official recommendations. As such, we have a typings field in our package.json file for each library which points to the correct d.ts file. This works fine for users of our cli and webpack, however it doesn't work for jspm users. We know Microsoft has a new solution, but it doesn't seem to be ready so we'd like to support the typings tool for jspm users. We can place typings.json files into our repos, no problem. We've done this with one repo as a test: aurelia-pal. However, when we try to install that using typings, we always get the old version, not our currently released version from npm. I had a look at your registry and it seems that someone has created entries for this already. I'm wondering if that is causing the problem. If we added typings.json files to all our libraries and then removed your registry entries, would typings always grab the latest release from npm? Would that fix our issue?

(Apologies for the double post...I didn't see this repo earlier.)

[EisenbergEffect]

Does this look correct for a typings.json with one dependency:

{
  "name": "aurelia-pal-browser",
  "main": "dist/aurelia-pal-browser.d.ts",
  "dependencies": {
    "aurelia-pal": "github:aurelia/pal"
  }
}

[EisenbergEffect]

@unional I'm getting ready to make a ton of repo updates, so just want to make sure I have this right. Can you do a quick look at the above sample and let me know if that looks good. I wasn't sure because I didn't see many examples I could pull from to be sure.

[blakeembrey]

@EisenbergEffect That's correct. The only thing you might run into is people will automatically be updated and it may break. You might want to specify a commit-ish, for example, a branch/tag/commit.

[unional]

@blakeembrey , @EisenbergEffect wants to get the master avoiding the overhead https://github.com/typings/typings/issues/601#issuecomment-226528238

Would it be a feasible short term solution?

Also, since aurelia-pal is already listed as a dependency on npm, do we need to re-list it on typings.json?

i.e.

{
  "name": "aurelia-pal-browser",
  "main": "dist/aurelia-pal-browser.d.ts"
}

may be sufficient if github: reads both package.json and typings.json.

To @EisenbergEffect , the github:<org>/<repo> would be useful for those dependencies that does not have package.json/typings specified. It serves as a supplement set of typings when consumer install it through typings install npm:aurelia-pal-browser and/or typings install jspm:aurelia-pal-browser

[EisenbergEffect]

I just got a bit confused :)

In my library pal I have this in a typing.json file

{
  "name": "aurelia-pal",
  "main": "dist/aurelia-pal.d.ts"
}

Then I have another library that is dependent on that, aurelia-pal-browser, so I put this in its typings.json file:

{
  "name": "aurelia-pal-browser",
  "main": "dist/aurelia-pal-browser.d.ts",
  "dependencies": {
    "aurelia-pal": "github:aurelia/pal"
  }
}

Is that correct? or should it be something else like this:

{
  "name": "aurelia-pal-browser",
  "main": "dist/aurelia-pal-browser.d.ts",
  "dependencies": {
    "aurelia-pal"
  }
}

Or something else altogether?

[unional]

Sorry to get you confused.

I'm not very familiar to how github: work so that question was to Blake: Does typings github:<org>/<repo> reads both package.json and typings.json?

If it does, then:

// since aurelia-pal-browser/package.json
{
  "dependencies": {
    "aurelia-pal": ...
  }
}

// aurelia-pal-browser/typings.json
{
  "name": "aurelia-pal-browser",
  "main": "dist/aurelia-pal-browser.d.ts"
}

If it does not, then:

// aurelia-pal-browser/typings.json
{
  "name": "aurelia-pal-browser",
  "main": "dist/aurelia-pal-browser.d.ts",
  "dependencies": {
    "aurelia-pal": "github:aurelia/pal"
  }
}

But as Blake mentioned, and you aware of, it will get the master all the time, which could break as you make changes to it before another release. Also, user will always get the latest version meaning there could be a version mismatch if the consumer uses an older version of aurelia.

That's why the best approach is to enable the consumer to do typings install jspm:aurelia-pal-browser which reads the local file (./jspm_packages/npm/aurelia-pal-browser/dist/aurelia-pal-browser.d.ts)

[EisenbergEffect]

We can't use jspm because the d.ts doesn't get installed by jspm. It doesn't load the full dist folder. I guess we could change our jspm configuration so that it did. Does typgings currently support jspm though? I thought that was under consideration but not yet implemented...

[blakeembrey]

@unional It only reads typings.json when resolving via github:. Otherwise dependencies collected in package.json resolution would blow up.

[unional]

I see. jspm: is WIP.

I try to spend time on it whenever I can because I need it at work also. (currently I'm doing jspm+npm double install approach on PRIVATE repos, sigh).

[EisenbergEffect]

I think we'll go with the github approach for now. I'm not super worried about people getting broken because we are about to RC and have a stable api. It's more about us improving the d.ts quality at this point. Eventually, we will switch to the new MS mechanism and I think that should solve any version issues after that point, should the arise.

[EisenbergEffect]

Ok, I'm still confused because typings doesn't seem to be doing what I expect. Here's what I have:

In github:aurelia/pal in the typings.json

{
  "name": "aurelia-pal",
  "main": "dist/aurelia-pal.d.ts"
}

In github:aurelia/pal-browser in the typings.json

{
  "name": "aurelia-pal-browser",
  "main": "dist/aurelia-pal-browser.d.ts",
  "dependencies": {
    "aurelia-pal": "github:aurelia/pal"
  }
}

Then I went into a project and ran typings install github:aurelia/pal-browser. It installed pal-brwoser but did not install the d.ts for pal. What am I doing wrong? @blakeembrey some assistance is gravely needed here. We are prepping our RC now and we have 40 repos we need to update for typings. It takes a lot of time and we don't want to screw it up and break all our TS users for our RC.

[blakeembrey]

@EisenbergEffect Check in the modules index.d.ts - the way typings works is by compiling it all down to a single .d.ts file - it doesn't do a flat dependency tree like JSPM/NPM/Bower does. Consider the current behaviour akin to "NPM v2" - it gets compiled into one single bundle for TypeScript to consume.

[EisenbergEffect]

I found it, ultimately ;) It just looked very odd.. I'm playing with it now. Thanks!

[EisenbergEffect]

@blakeembrey I honestly can't get it to work. I've got VS Code. I created a tsconfig.json file. I ran npm install and then did jspm install aurelia-pal-browser. After that I did typings install github:aurelia/pal-browser. Then I created a TypeScript file and attempted to import something from aurelia-pal which is a dependency of aurelia-pal-browser. VS Code can't find the module. It will find pal-browser, but not its dependency. It's hard to understand exactly why because I don't understand the format of the generated files, but the module for pal is declared as declare module '~aurelia-pal-browser~aurelia-pal/dist/aurelia-pal' { ... } which obviously isn't correct.

Can you explain what I'm doing wrong. I'm just trying to get this working in isolation because it's going to take hours for me to update all our stuff and I don't want to have to do it again.

[unional]

If you want to access aurelia-pal in your consuming project, you also need typings install github:aurelia/pal Just like in npm by installing aurelia-pal-browser you won't be able to use aurelia-pal, its dependency.

[EisenbergEffect]

Ok, got it. So, should I even go through the trouble of declaring the dependencies in my typings.json files at all then? That's not going to help our consumers, they'll have to manually install them anyway (or we'll have to list them all out in our skeleton instead of the single bootstrapper module.)

On the plus side, it's much easier for me to not go setting up all the deps. I just want to make sure I'm not missing something. Again, thanks for bearing with me in figuring this out. I really have no clue before this week how this infrastructure actually worked ;)

[unional]

This is mostly for supporting jspm I assume.

For npm, unless your module is using dependencies that in turn using dependencies that does not have a build in typings (yes, two levels deep), you don't need to declare the dependencies like that in typings.json

See this example: https://github.com/typings/core/blob/master/typings.json#L19 typings/core depends on popsicle which depends on arrify etc that does not have typings in their package: https://github.com/blakeembrey/popsicle/blob/master/typings.json#L10

Therefore, for typings/core to compile properly with popsicle, it needs to install popsicle typings using typings install npm:popsicle to get those additional typings as tsc cannot resolve them automatically.

For jspm, since tsc will not do anything at all, your currently solution is to use typings install github:aurelia/pal, typings install github:aurelia/pal-browser to get those typings.

When jspm: is implemented, it will read package.json to resolve the dependencies as specified by jspm to so that it will just work like npm, i.e. by that time your typings.json don't need to specify the dependencies as you are doing right now (unless you want to continue supporting typings install github:... syntax, which means to do it correctly, you need to specify the version/commish as Blake said, which is what you tried to avoid).

Does this help?

[EisenbergEffect]

I think so. We at least have a course of action for now. We can revise when more capabilities both from Typings and Microsoft come online. Thanks again for bearing with me on this :)