How to get working intellisense when using require in *.server.js files

[chaorace]

"*.server.js" refers to the server-side scripts embedded in Fluent files via the new Now.include API in SDK v3. Currently the stock templates for these provide no require intellisense... that's what this guide will help you fix!

Import path completion!

Types!

---

For the purposes of this demonstration, I'll be assuming that your src/fluent directory is configured according to the same tsconfig.json / tsconfig.server.json / tsconfig.client.json pattern as demonstrated in the official examples: permalink.

First, we need to inform the typechecker that we're in a CommonJS-like environment and that we care to receive typecheck errors. This can be achieved with the following additions to your server.tsconfig.json:

"compilerOptions": {
  "module": "CommonJS",
  "checkJS": true
}

As-is, this isn't enough to get intellisense because there's a fundamental mismatch in how ./ file paths get resolved in Fluent vs. CommonJS. For unimportant reasons further detailed in the below aside, it's basically impossible to reconcile ./ between the two systems.

Expand for explanation...

In Fluent ./ acts as an alias for your package's sys_module prefix (e.g.: x_org_scope/app/0.0.0/). Meanwhile, CommonJS interprets ./ in the standard fashion: as a basic path specifier relative to the location of the current file. These two interpretations have almost no real overlap, meaning the only *true* fix is to intercept/replace the pathstring in-between compilation steps with the help of a custom plugin -- too bad fluent compiler doesn't have plugins!

As luck would have it, however: we don't have to use ./! If we simply access the package by name instead, both systems will work in agreement. In other words, we'll need to...

• Stop doing this: require('./dist/server/lib.js')
• Start doing this: require(my-package/lib.js) ("my-package" should match the name in your package.json)

Name-based access like this is identical both ways, so making the switch is (in theory) the complete solution to our problem! In practice, though? We've still got a little more configuration to do...

First, add the following additional compiler options to tsconfig.server.json. These changes instruct the typechecker where to find the local files associated with our package name references:

"compilerOptions": {
  "baseUrl": "../server",
  "paths": {
    "my-package/*": "../server/*"
  }
}

Next, update package.json with a submodule export mapping so that the require API will understand how the full path associated with your sys_modules translate to the package's filetree:

"exports": {
  "./*": "./dist/server/*.js"
}

Once everything's configured, simply restart your text editor and try editing one of your *.server.js files! If the typechecker is properly configured, you should now have fully functional intellisense on your module imports, per the top screenshots.

Once confirmed, finish the process up by building/deploying/testing your package. Please pay special attention here because the only method of verifying the proper working of require is actually running through the code!

[venkat-kaluva]

Thanks for the detailed explanation. We will update the SDK docs to include this.