Published on

Using jsconfig.json

Authors

Today I was busy working on a Javascript code base where I had to track down and fix a bug in production.

After spending about an hour tracking down the bug I found it was related to the incorrect field being used on an object so for example I used person.name instead of person.first_name 🙈.

I decided enough was enough so I looked for some sort of linting solution to help pick these issues up ideally as early as possible. Unfortunately I had the following constraints:

  1. I could not install any nodejs modules
  2. I did not have a package.json to work with
  3. I could not use Typescript

What I did have was intellisense in VS Code that looked as if it could assist somehow.

After a bit of Googling I found this article which explains how Javascript intellisense works in VS Code. Basically it has a default way of working but a jsconfig.json file in the root of the project can be used to tweak it more. The placement of this file tells VS Code where the root of your project is.

After a bit more Googling I found out that I could define types using .d.ts files.

The jsconfig.json file can be configured to point to a folder with Typescript types in and you can then add JSdoc comments above whatever you want VS codes intellisense for.

I put my jsconfig.json file in the root of the project and configured it as follows:

{ 
   "compilerOptions": { 
     "target": "ES2016", 
     "checkJs": true, 
     "module": "commonjs" 
   }, 
   "include": ["./typings/**/*.d.ts", "./**/*.js"] 
 }

In the above:

  • include both tells VS code:
    • where to find my type definitions .typings/**/*.d.ts
    • What files to run intellisense on . /**/*.js

To tell VS Code to use intellisense for types I can do this using comments as follows:

  • Above a method:
/**
 * @param {import("../typings/person").address_details} address  
* @returns {number} 
 */
 const doAddressCalcs = (address) => {
 // the actual method logic here
 };
  • Above a variable:
/** @type {import  ("../typings/person")}.person_details person*/
let person = {};

For the above:

  1. Type Import: VS code helps me work out where to import the data type from.
  2. Folder name: The folder name for the type files seems irrelevant as long as you reference it correctly in your jsconfig.json file
  3. returns: you can just have returns with nothing after it (VS code won't know the return type then)
  4. .d.ts: you can just use .ts without the .d but the .d seems to be the convention when defining schema types
  5. type declarations: you can define types as you would normally in typescript. You need to export each type.

An example types file for a person is defined below, person.d.ts:

export type gender = 'male' | 'female';

export type address_details = {
   line_1: string;
   line_2?: string;
   state: string;
   city: string;
   zip_code: string;
};

export type person_details = {
   first_name: string;
   middle_name?: string;
   surname: string;
   age: number;
   gender: gender;
   address?: address_details;
   
};