JavaScript and Node.js walkthrough

[DanielRosenwasser]

I figured it would be worth opening a new PR for this one.

The feedback I got on #151665 was effectively to scope things down and make a walkthrough that's just Node.js and JavaScript. Doing that brings some parity with other languages like Python and reduces the need to introduce HTML, at the expense of losing the convenience of the browser and web development.

Fixes microsoft/TypeScript#48489
Ticks a box off on #144062

Here's the current TODOs, with some specific callouts that I'd appreciate some input on.

• Media Assets: I'll need to work with @misolori @daviddossett on these.
  • Walkthrough icon
  • Media for each step (currently just a TODO page)
• Workflow and Phrasing
  • I added a button to restart VS Code in case node isn't present on the terminal. Should I?
  • Is there a better way to have a user graduate from running on the terminal to debugging?
• Polish
  • Can we either hide or fill in the step for installing Node.js? Is there an easy way to determine whether Node.js is already installed? (@mjbvz)
  • In the last step, if a user tries to run/debug a single JavaScript file in their root directory, the debugger takes forever to start. Can we fix this? (@connor4312)
• Experiments: Let's plumb these through (@devinvalenciano @isidorn @digitarald). Good experiments to start with:
  • How do we pitch this? Is it a "get started with JS" or a "get started with Node.js and JS" walkthrough?

[mjbvz]

Looks like a great start!

For determining if node is on the users's system, I think you'll have to use child_process to check. Hopefully we can catch the majority of installs. Here's an example of how we find git:

vscode/extensions/git/src/git.ts

Line 80 in 81e6a02

function findGitDarwin(onValidate: (path: string) => boolean): Promise<IGit> {

[DanielRosenwasser]

@mjbvz seems fine but then I have to do that every time the extension is activated, right? It seems wasteful to spawn that process the first time a .ts/.js file is opened. I can do it, but it probably makes sense for this to live in its own extension long-term.

[DanielRosenwasser]

Actually, I seem to be having some trouble getting the walkthrough wired up with that. I'll push up my new changes in a minute but the current state is this:

I've defined a new command

// extensions/typescript-language-features/src/commands/jsWalkthrough.ts
// ...

export class NodeInstallationFoundCommand {
	public static readonly id = 'javascript-walkthrough.commands.nodeInstallationFound';
	public readonly id = 'javascript-walkthrough.commands.nodeInstallationFound';
	public execute() {
		vscode.window.showInformationMessage('yay it happened');
	}
}

and registered it

// extensions/typescript-language-features/src/commands/index.ts
// ...

	commandManager.register(new NodeInstallationFoundCommand());

and fired the command after it's registered and after I check for if Node exists.

// extensions/typescript-language-features/src/extension.ts
// ...

	hasNode().then(
		async (isInstalled) => {
			if (isInstalled) {
				await vscode.commands.executeCommand('javascript-walkthrough.commands.nodeInstallationFound');
				vscode.window.showInformationMessage('it is installed :)');
			}
			else {
				vscode.window.showErrorMessage('it aint installed :(');
			}
		}
	);

When the extension gets activated, I do see the information message; however, in the walkthrough I have an onCommand completion event

          {
            "id": "walkthroughs.jsWelcome.downloadNode.forMacOrWindows",
            "title": "%walkthroughs.jsWelcome.downloadNode.forMacOrWindows.title%",
            "description": "%walkthroughs.jsWelcome.downloadNode.forMacOrWindows.description%",
            "media": {
              "markdown": "resources/walkthroughs/TODO.md"
            },
            "when": "isWindows || isMac",
            "completionEvents": [
              "onLink:https://nodejs.org/en/download/",
              "onCommand:javascript-walkthrough.commands.nodeInstallationFound"
            ]
          },

but it doesn't seem like that step is marked as completed.

Anything obvious I'm doing wrong?

[DanielRosenwasser]

Hey all, here's the current status.

First, the walkthrough just has 4 steps now

• Install Node.js
• Create a JS File
• Run & Debug the JS File
• Read more

The notable stuff on each step is

• "Install Node.js" still segments you based on Linux vs Windows/Mac. I don't bother to do any auto-detection to see whether Node.js is already installed. This is partially because the API seems to have issues with marking a step as completed programmatically. @karrtikr got around this in Improve how to notify the user they don't have Python installed when installing the Python extension for the first time vscode-python#19379 by just hiding the tile with a context variable. I'm probably not going that route in this PR.
• "Create a JS File" is minimal. I just use console.log.
• "Run & Debug" is merged into a single step.

  • I mention running from the terminal, but I don't present a button to do it.

  • I do check that Node was installed when clicking the debug button. I give the user the option of Reload VS Code, Try Debugging Anyway, and Dismiss.

    

I will need assets for each step, along with a walkthrough icon which should probably use the JS community logo, the Node.js logo, or both. I've created some tentative assets, which I derived from the Python walkthrough, but they don't appear aligned, so I need some help on that.

I don't expect this to go into the August release at this point, but the sooner the better.

[daviddossett]

I'll add the assets to this PR this week 👍

[daviddossett]

Updated icon and SVGs

CleanShot.2022-09-02.at.09.55.04.mp4

[mjbvz]

The icon.png file is used in VS Code's extension UI. I think it would be confusing to use a js specific one for the JS/TS language features extension

[daviddossett]

The icon.png file is used in VS Code's extension UI. I think it would be confusing to use a js specific one for the JS/TS language features extension

That's fair. I'll replace with something less specific.

[DanielRosenwasser]

Huh - is there no way to provide an alternative icon for a walkthrough? (@lramos15)

[lramos15]

Not sure I understand the question, what do you mean by alternative icon @DanielRosenwasser

[daviddossett]

Not sure I understand the question, what do you mean by alternative icon @DanielRosenwasser

If I understood correctly I think he means that these icons are currently both using the same source icon. I.e. you can't use a different icon for a walkthrough vs. the extension itself.

[DanielRosenwasser]

That's correct - but I don't think we should block this PR over the icon. I would rather begin experimenting here, and in the future use a different icon if walkthroughs eventually do support their own icons.