Debugging SPFx Solutions in Github Codespaces

[shurick81]

What type of issue is this?

Question

What SharePoint development model, framework, SDK or API is this about?

💥 SharePoint Framework

Target SharePoint environment

SharePoint Online

What browser(s) / client(s) have you tested

• 💥 Internet Explorer
• 💥 Microsoft Edge
• 💥 Google Chrome
• 💥 FireFox
• 💥 Safari
• mobile (iOS/iPadOS)
• mobile (Android)
• not applicable
• other (enter in the "Additional environment details" area below)

Additional environment details

• SPFx 1.13.1
• Node.js 14

Issue description

Would it be possible to debug SPFx solutions using Github workspaces?

When I just try to run the solution as is, I get an error in the hosted workbench:

https://steria.sharepoint.com/_layouts/15/workbench.aspx?debug=true&noredir=true&debugManifestsFile=https://shurick81-alexsapozhkov-codespaces-demo-00-77p5r5x73xrpw-4321.githubpreview.dev/temp/manifests.js

I try to dig deeper and checking https://shurick81-alexsapozhkov-codespaces-demo-00-77p5r5x73xrpw-4321.githubpreview.dev/temp/manifests.js in the browser, I'm getting a Bad Gateway error:

Then I try to fix the latter one and do the following changes (that helps for running SPFx gulp serve in containers: https://github.com/pnp/docker-spfx#known-issues):

1. Modify node_modules\@microsoft\spfx-heft-plugins\lib\plugins\webpackConfigurationPlugin\WebpackConfigurationGenerator.js:393

const debugBaseUrl = `${serveConfig.https ? 'https' : 'http'}://${serveConfig.hostname || 'localhost'}:${serveConfig.port || 4321}/${distFolderName}/`;

to:

const debugBaseUrl = `${serveConfig.https ? 'https' : 'http'}://localhost:${serveConfig.port || 4321}/${distFolderName}/`;

2. map the workbench to 0.0.0.0, by modifying the ./config/serve.json file in your SharePoint Framework project to:

{
  "$schema": "https://developer.microsoft.com/json-schemas/core-build/serve.schema.json",
  "port": 4321,
  "hostname": "0.0.0.0",
  "https": true,
  "initialPage": "https://enter-your-SharePoint-site/_layouts/workbench.aspx"
}

I get the response when I request js file then:

However, when I try to run the hosted workbench, I get new issues:

When I look into developer tools in the browser, I can see that the browser is getting proper response from https://shurick81-alexsapozhkov-codespaces-demo-00-77p5r5x73xrpw-4321.githubpreview.dev/temp/manifests.js but then it is trying to access resources from https://localhost:4321/temp/manifests.js and of course fails:

I might guess that the reason is that the file https://shurick81-alexsapozhkov-codespaces-demo-00-77p5r5x73xrpw-4321.githubpreview.dev/temp/manifests.js actually contains a lot of references on the localhost:

[ghost]

Thank you for reporting this issue. We will be triaging your incoming issue as soon as possible.

[AJIXuMuK]

Hi @shurick81 - in 1.14 beta (that should be released soon) we introduced new configuration called ipAddress. This property is used explicitly wind up the server and doesn't impact the debugging urls.
Although, it was done for Docker scenarios, it might be helpful here as well. You can specify both ipAddress and hostname to achieve your needs.
Please, share the results with us, too!

[DonKirkham]

When you open an SPFx project in Codespaces, you are getting a new VM based on the default Linux container (unless you have configured .devcontainers). Regardless, because this is a new "machine," you have to generate the developer certificate, download it to your local machine and install it in the Certificate store. If not, localhost will not deliver the manifest.js file to your browser and you get the initial errors you are seeing. (Error loading manifest.js)

[shurick81]

@DonKirkham, thanks, but as I noted above, getting manifest.js was not prevented by certificate, but only by the host name configuration. I'm not sure how it was in earlier times of Codespaces, but right now its proxy is exposing SSL with it's own certificate, so adding the certificate from container to the client device should not be necessary.

[DonKirkham]

I didn't realize you were attempting this from the browser. My bad. I hope you get this working as I gave up a while back. I open the Codespace in VS Code on my device and then it works just like Docker or WSL.

Hats off for attacking this. I hope we can get it solved.

[shurick81]

I have run a few tests with a new project, scaffolded with SPFx 1.14.0 that was released just today :).

I tested running in Github Codespaces a few different configurations in /config/serve.json

1. "ipAddress": "0.0.0.0"

{
  "$schema": "https://developer.microsoft.com/json-schemas/core-build/serve.schema.json",
  "port": 4321,
  "ipAddress": "0.0.0.0",
  "https": true,
  "initialPage": "https://steria.sharepoint.com/_layouts/15/workbench.aspx"
}

This worked just fine in a local container or in the Visual Studio Code Remote Container but when I try to use it with Github Codespaces, I still get this behavior: I can get /temp/manifests.js file in the browser on https://shurick81-alexsapozhkov-codespaces-demo-01-96j5q5x6h7xgq-4321.githubpreview.dev/temp/manifests.js but it is full of "https://localhost" references in the content:

And the hosted workbench throws the error, probably because of this localhost reference:

I noticed additional issue after that. If I stop gulp serve and immediately run it again, I get 502 error on https://shurick81-alexsapozhkov-codespaces-demo-01-96j5q5x6h7xgq-4321.githubpreview.dev/temp/manifests.js:

This additional problem is only solved after I rebuild the whole container in Github Codespaces.

2. "hostname": "shurick81-alexsapozhkov-codespaces-demo-01-96j5q5x6h7xgq-4321.githubpreview.dev"

{
  "$schema": "https://developer.microsoft.com/json-schemas/core-build/serve.schema.json",
  "port": 4321,
  "hostname": "shurick81-alexsapozhkov-codespaces-demo-01-96j5q5x6h7xgq-4321.githubpreview.dev",
  "ipAddress": "0.0.0.0",
  "https": true,
  "initialPage": "https://steria.sharepoint.com/_layouts/15/workbench.aspx"
}

Behavior is the same as in case 1.

3. "hostname": "*"

{
  "$schema": "https://developer.microsoft.com/json-schemas/core-build/serve.schema.json",
  "port": 4321,
  "hostname": "*",
  "ipAddress": "0.0.0.0",
  "https": true,
  "initialPage": "https://steria.sharepoint.com/_layouts/15/workbench.aspx"
}

Behavior is the same as in case 1.

Additional info

Here's the command that I used for scaffolding:

yo @microsoft/sharepoint --solution-name helloworld --component-type webpart --component-name hello-world-webpart --component-description "HelloWorld web part" --is-domain-isolated false --framework none --environment spo --skip-feature-deployment false

This is the repo:

https://github.com/alexsapozhkov/codespaces-demo-01

[shurick81]

Do I get it right that in order to make Github Codespaces web site https://shurick81-alexsapozhkov-codespaces-demo-01-96j5q5x6h7xgq-4321.githubpreview.dev to host assets, we should somehow make sure that on this picture, https://user-images.githubusercontent.com/11289124/154579459-d1dbb786-9711-48c3-8e40-ee3cfca61424.png, instead of https://localhost, the manifests.js file should refer to https://shurick81-alexsapozhkov-codespaces-demo-01-96j5q5x6h7xgq-4321.githubpreview.dev? Or is it completely wrong assumption

[anoopt]

@shurick81 - Can you please try to

• Open the code in VS code using the Remote explorer extension
  
• In the VS code terminal run gulp serve
• You should see a message that port 4321 is forwarded
• In case you see Error loading debug manifests message - check if the manifest.js is being served from localhost first and then you can solve that error using this post
• Or you can run the below commands in VS code terminal and install the certificate on your local machine

gulp trust-dev-cert
cp ~/.gcb-serve-data/gcb-serve.cer ./spfx-dev-cert.cer
cp ~/.gcb-serve-data/gcb-serve.cer ./spfx-dev-cert.pem

[shurick81]

Ok, I run "View: Show Remote Explorer"

in VS code terminal I run gulp serve

Where should I see that message that port 4321 is forwarded?

I can see this if I switch tab to "PORTS":

I can see that the manifests file is served:

What certificates on what local machine? On my local machine when I access manifests, they are served behind the application proxy that is using a publicly valid certificate:

[anoopt]

Interesting. I think I have seen this in the past when I used the spfx docker image to create the codespace. Can you try without the spfx docker image?

• Create an empty repo in GitHub with just a README file
• Create a codespace for that repo in github.com
• Open that codespace in VS code
• In the terminal, run the command npm install gulp-cli yo @microsoft/generator-sharepoint --global to install the SPFx pre-reqs
• After that create a new SPFx project with yo @microsoft/sharepoint
• Once complete run gulp serve
• You should the below message in VS code at the bottom right
  
• In the Ports tab you should see ports 4321 and 35729 being forwarded to 127.0.0.1
  

[shurick81]

The picture you are showing with ports @anoopt, it is not from Codespaces, it is from remote containers, right? In this case yes it will be 127.0.0.1 on your machine and it will be exposed via the same SSL certificate that you set up in browser. Github Codes Codespaces is different in this sense: it is exposed on the remote host. That is why it is important that manifests refer to the remote host name too. You can see in my previous comments that probably the issue is that even though all assets are hosted on the shurick81-alexsapozhkov-codespaces-demo-01-96j5q5x6h7xgq-4321.githubpreview.dev host name, manifests are referring to localhost. As a result, the browser can reach manifests file without issues but then browser executes it and trying to reach resources on localhost, which will never work for Github Codespaces.

[anoopt]

Thanks @shurick81 - the ports are from codespaces as you can see it under Origin column in the screenshot.

What I have noticed is when I have the .devcontainer folder with the files that you have in your repo and create a codespace for that repo, then the codespace gets created with the ``m365pnp/spfx:1.14.0` image. With that image the ports get forwarded to the codespace host and not to 127.0.0.1.

So, if you create new repo without the .devcontainer folder, create a codespace for that and then do the initial SPFx setup on that codespace, open the codespace on VS code on your machine, you should see the ports forwarded correctly.

Not sure if the image m365pnp/spfx:1.14.0 in devcontainer.json is not being liked by codespaces. Need to check.

[shurick81]

Thanks @anoopt, you were totally right, now it is working in codespaces in VS and everything exposed on 127.0.0.1.

I just copied the same code but removed .devcontainer directory and then created a codespace "adhoc": https://github.com/alexsapozhkov/codespaces-test-03. Here's the result:

And this is considering that I don't even have Docker running on this machine, just VS and browser. The container is completely remote but somehow it is exposed on the 127.0.0.1...

How will I sleep now without understanding how this exposure is controlled...

[shurick81]

I digged a bit deeper now and the only change I needed to do in order to make the port available on the localhost is this: alexsapozhkov/codespaces-test-04@7e63720
The image m365pnp/spfx:1.14.0 is just fine. The only problem was the configuration of ports that dictated Codespaces to forward them to https://*.githubpreview.dev. See more: https://code.visualstudio.com/docs/remote/devcontainerjson-reference#_port-attributes

[shurick81]

I think we could close this issue since debugging is now working with Codespaces. However, then we need to open a new issue regarding debugging without Visual Studio installed, with just browser. When I use just browser, without Visual Studio, it is of course not possible to expose the container port on the localhost, so the port is forwarded to https://*.githubpreview.dev.

In such scenario, gulp serve should generate assets that refer to the remote host name in *.githubpreview.dev space. But that should be probably registered as a separate issue?

[michaelmaillot]

Hi everyone,

First of all: thanks for all the investigation, really interesting walkthrough!

I've started to have a look at running a forked repo with GitHub Codespaces to test the code and encountered some issues...

First one is when using Codespaces app (provided by VS Code but as a separate instance). I got the same forwared URL as mentioned above ("reimagined-spork-blablabla-4321.app.github.dev" here).

devcontainer.json

{
	"name": "SPFx",
    "image": "m365pnp/spfx:1.17.3",

	// Set *default* container specific settings.json values on container create.
	"customizations": {
        "vscode": {
            "settings": {
                "terminal.integrated.shell.linux": "/bin/bash"
            },
            // Add the IDs of extensions you want installed when the container is created.
            "extensions": [
                "dbaeumer.vscode-eslint",
                "ms-vscode.vscode-typescript-tslint-plugin"
            ]
        } 
	},

	// Use 'forwardPorts' to make a list of ports inside the container available locally.
	"forwardPorts": [4321, 5432, 35729],
    "portsAttributes": {
		"4321": {
			"protocol": "https",
			"label": "Manifest",
			"onAutoForward": "silent",
			"requireLocalPort": true
		},
		"35729": {
			"protocol": "https",
			"label": "LiveReload",
			"onAutoForward": "silent",
			"requireLocalPort": true
		}
	},
	"postCreateCommand": "bash .devcontainer/spfx-startup.sh",
	"remoteUser": "node"
}

serve.json has the same config as declared here.

Ports are declared like this:

I've run the gulp trust-dev-cert command, then run the local server and I can load the manifest file with forwarded URL in my browser. But when loading in the Workbench, I got a connection refused error, which is trying to get from "https://localhost:4321".

So I've tried directly from VS Code with which I have forwarded URL to localhost:

But now I got a certificate issue:

devcontainer.json

{
	"name": "SPFx",
    "image": "m365pnp/spfx:1.17.3",

	// Set *default* container specific settings.json values on container create.
	"customizations": {
        "vscode": {
            "settings": {
                "terminal.integrated.shell.linux": "/bin/bash"
            },
            // Add the IDs of extensions you want installed when the container is created.
            "extensions": [
                "dbaeumer.vscode-eslint",
                "ms-vscode.vscode-typescript-tslint-plugin"
            ]
        } 
	},

	// Use 'forwardPorts' to make a list of ports inside the container available locally.
	"forwardPorts": [4321, 5432, 35729],
    "portsAttributes": {
		// "4321": {
		// 	"protocol": "https",
		// 	"label": "Manifest",
		// 	"onAutoForward": "silent",
		// 	"requireLocalPort": true
		// },
		"35729": {
			"protocol": "https",
			"label": "LiveReload",
			"onAutoForward": "silent",
			"requireLocalPort": true
		}
	},
	"postCreateCommand": "bash .devcontainer/spfx-startup.sh",
	"remoteUser": "node"
}

I tried suggestion above (generating the .cer file, downloading it locally and installing it on my machine) without success.

Even if what suggested @anoopt above (starting from a fresh repo then generate its Codespaces) works, my concern is regarding the use case when you want to test someone's branch / repo quickly without having to install the prerequisites. We should be able to generate a Codespace from a repo and simply launch a local browser.

Does someone figured out with a similar use case or am I doing this wrong?

[shurick81]

@michaelmaillot, are you trying to use Codespaces from Visual Studio or from a web browser? I only managed to get it working from Visual Studio

[michaelmaillot]

I'm trying to use GitHub Codespaces from VS Code.

[shurick81]

I don't know why it did not work with installing certificate in your system: the error looks exactly like the certificate is not trusted. If you want, we could try troubleshoot this together.

But in general, I think you are totally right: we need this use case just available from the SPFx tool belt, it should not require these strange troubleshooting steps when one just wants to share your commit with other people in their team.

[michaelmaillot]

Thanks for confirming that!

I would love to get some help / insights about that, maybe I'm missing a little bit of something. I'm available on Twitter, Teams,... 🙂