Improve highlighting changes to files in SPFx project upgrade output

[sympmarc]

I've upgraded one of my projects to SPFx 1.6.0 using the @next version of the CLI. After following all the steps, I'm seeing errors when I run gulp serve which look like they come from the updates to tsconfig.json.

I'm attaching the output of the command:
office365 spfx project upgrade --toVersion 1.6.0
as well as the tsconfig.json file after I made the changes and the errors I see in the terminal. See lines 29-34 in errors.txt for the errors about the include and exclude options.

upgrade-1.6.0.zip

It's certainly possible I misread the instructions, but I've checked a few times and I think I've got things right.

[waldekmastykarz]

include and exclude shouldn't be under compilerOptions but rather on the same level.

You can see the difference when you compare two findings, one that involves changing the compilerOptions section and one that refers to adding a property on the root level of the JSON file:

FN012011 tsconfig.json compiler options outDir | Required

Update tsconfig.json outDir value

In file ./tsconfig.json update the code as follows:

{
  "compilerOptions": {
    "outDir": "lib"
  }
}

File: ./tsconfig.json

FN012012 tsconfig.json include property | Required

Update tsconfig.json include property

In file ./tsconfig.json update the code as follows:

{
  "include": [
    "src/**/*.ts"
  ]
}

File: ./tsconfig.json

Do you have an idea how we could make the difference between the two clearer?

[sympmarc]

Doh! I honestly thought that was what I did.

To make it easier, I wonder if you could show the whole file with the changes required highlighted. You're showing JSON snippets without the surrounding context and that's probably part of what caused me to make the mistake. Unfortunately, there's no good way to highlight lines of code in markdown, right?

[waldekmastykarz]

I can definitely see it be clearer to highlight the affected lines like you mentioned. I don't think vanilla markdown has anything for that, but maybe there are some other options that we could use. Let's investigate it 💪

[waldekmastykarz]

@sympmarc in v2.10 of Office 365 CLI we've implemented a new SPFx project upgrade report based on VSCode CodeTour. Would that report provide you the additional context you were looking for?

[sympmarc]

@waldekmastykarz I'm not sure what that means. I hear you mention it on a call, but I didn't know what it was. (I'm lame.) I just looked at the docs, and I didn't see anything. Is there a way for me to try it out?

[garrytrinder]

Hey @sympmarc we are lacking in some docs on this but we will get some out there, for now though this might help.

• CodeTour is an extension for VSCode which you can download from the marketplace
• You can use spfx project upgrade --output tour which generates a tour file in the project
• You can then navigate the "tour" in VSCode which will take you through the upgrade steps one by one, visually pointing out the changes you need to make in the code project

Reference - Starting Tours > https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour#starting-tours

[waldekmastykarz]

Sorry for cutting a corner @sympmarc and thank you for the explanation @garrytrinder. We need to ensure that our docs properly describe this.

[sympmarc]

You should always assume I'm dumber than you are, @waldekmastykarz. :) I'll give it a try!

[sympmarc]

I'm going to try this today on a project I built for SharePoint 2019 (thus v1.4.1) and will upgrade to 1.10.0. Should be interesting!

[waldekmastykarz]

Crossing my fingers! Looking forward to hear what you think 😊

[sympmarc]

Ok, I'm going to ask some dumb questions right here in case it helps someone else...

My existing solution seems to be 1.9.1, but targeted to SP2019, which I believe uses 1.4.1?

From .yo-rc.json:

  "@microsoft/generator-sharepoint": {
    "environment": "onprem19",
    "framework": "none",
    "isCreatingSolution": true,
    "version": "1.9.1",
    "libraryName": "matter-extension",
    "libraryId": "9508d879-117e-4736-8cbd-01eafec199b0",
    "packageManager": "npm",
    "componentType": "extension",
    "extensionType": "ApplicationCustomizer"
  }

What I want to do is take one of the solutions in the project (it contains an Extension and a Web Part) and contribute it as a sample to sp-dev-fx-webparts.

I thought I'd need to upgrade from 1.4.1 to 1.10. 0. I also want to pull the Web Part out of the solution in order to genericize it as a sample.

I don't want to upgrade the existing solution, because it's an ongoing project with SharePoint 2019. But I would see this as a common need as orgs move from on premises 2019 or 2016 to SPO.

Suggestions? I thought I know how to do all this, but I'm finding I must not.

[waldekmastykarz]

This isn't a dumb question and I believe you've uncovered something we haven't taken into account so far. Up until now, we've been assuming that the version of the generator used to create the project = the version of SPFx. We've found this to me more reliable than looking at the versions of packages in package.json, which in the 1.0.0-1.4.0 timeframe were inconsistent. What we didn't take into account, that you can use generator 1.9.1 and create a project for on-prem which would be using 1.4.1. In this case, we'd incorrectly assume that your project is on 1.9.1 rather than on 1.4.1.

We've been planning to improving project version detection #1487 and #1488. I believe these two fixes should address the issue that you're seeing. Until that is fixed, the easy workaround would be to change the version in .yo.rc.json to 1.4.1 and re-run the upgrade.

Sorry for the trouble.

[sympmarc]

I love it when my dumb questions aren't so dumb. At the very least, this could be a change in the project-upgrade doc page to talk about solutions built for 2016 or 2019?

I'll let you know how it goes...

---

If your solution has been built for SharePoint 2016 or 2019, check .yo-rc.json before running project-upgrade.

If you see:

  "environment": "onprem19",

then change the version line to:

    "version": "1.4.1",

If you see (not sure this is right, as I don't have an example):

  "environment": "onprem16",

then change the version line to:

    "version": "1.1.0",

After making these changes, you can go ahead and run project-upgrade.

[waldekmastykarz]

We're planning to update the project version detection logic so that people don't need to modify their projects.

[waldekmastykarz]

Thinking of it, I've created a separate issue to track it (#1647) because it's slightly different from what we had in mind and it's a test case that we should've also had in our tests. Once again, thank you for bringing it up 👍

[sympmarc]

The CodeTour approach is awesome. See my blog post on why it's so useful.

So long, and thanks for all the fish.

[sympmarc]

I'm not sure if this is something you can change, but some of the steps feel a little cryptic. Here's an example. I know I need to add this

{
  "resolutions": {
    "@types/react": "16.8.8"
  }
}

into the JSON file, but the tour step is sitting smack in the middle of the dependencies element. If I'm not mistaken, I need to add the resolutions property as a peer of dependencies. I think it might be confusing to people.

[waldekmastykarz]

Good catch! Yes, this is a known issue and @hugoabernier is working on it #1602. We hope that we will be able to ship it shortly 😊