diff --git a/integrations/vscode/README.md b/integrations/vscode/README.md
index 548f369..2932f3b 100644
--- a/integrations/vscode/README.md
+++ b/integrations/vscode/README.md
@@ -4,18 +4,52 @@
 
 ## Features
 
-This extension adds support
-for formatting Nix files
+This extension adds built-in editor support
+for formatting Nix files automatically
 with [Alejandra](https://github.com/kamadorueda/alejandra).
 
-## Requirements
+## Getting started
 
-Make sure to install [Alejandra](https://github.com/kamadorueda/alejandra) in your system first.
+1.  Make sure to install
+    [Alejandra](https://github.com/kamadorueda/alejandra)
+    in your system first
+    as explained [here](https://github.com/kamadorueda/alejandra).
 
-## Settings
+1.  Install the vscode extension and reload the window (just close and open again).
 
-This extension contributes the following settings:
+1.  Open a Nix file,
+    do a right click
+    and you should be able to see "Format Document" in the menu.
 
-- `alejandra.path`: Specifies an alternative full path to the Alejandra executable.
+    Alternatively, it will be formatted automatically when you save the file.
 
-  By default we will use the Alejandra installed in your system.
+Enjoy!
+
+# Troubleshooting
+
+If you encounter a problem
+please let us know in the
+[issues section](https://github.com/kamadorueda/alejandra/issues).
+
+The most probable causes of failure are:
+
+- Not having Alejandra installed in your system.
+
+  In this case please follow the instructions
+  [here](https://github.com/kamadorueda/alejandra).
+
+- A misconfiguration.
+
+  In this case please make sure that your config contains the following values:
+
+  ```json
+  {
+    "[nix]": {
+      "editor.defaultFormatter": "kamadorueda.alejandra",
+      "editor.formatOnPaste": true,
+      "editor.formatOnSave": true,
+      "editor.formatOnType": false
+    },
+    "alejandra.program": "alejandra"
+  }
+  ```
diff --git a/integrations/vscode/extension.js b/integrations/vscode/extension.js
index b476170..82c4288 100644
--- a/integrations/vscode/extension.js
+++ b/integrations/vscode/extension.js
@@ -1,31 +1,72 @@
-const vscode = require('vscode');
-const { execFileSync } = require("child_process");
+const { execFile } = require("child_process");
+const vscode = require("vscode");
 
-function activate(context) {
-	const config = vscode.workspace.getConfiguration("alejandra");
+const activate = (_) => {
+  const outputChannel = vscode.window.createOutputChannel("Alejandra");
 
-  context.subscriptions.push(
-    vscode.languages.registerDocumentFormattingEditProvider("nix", {
-      provideDocumentFormattingEdits: (document, _, _) => {
-        const range = new vscode.Range(0, 0, document.lineCount, 0);
+  vscode.languages.registerDocumentFormattingEditProvider("nix", {
+    provideDocumentFormattingEdits(document, _) {
+      const config = {
+        alejandra: vscode.workspace.getConfiguration("alejandra"),
+      };
 
+      return new Promise((resolve, reject) => {
         try {
-          const formattedText = execFileSync(config.path, { input: document.getText() });
-          return [vscode.TextEdit.replace(range, formattedText.toString())];
-        }
-        catch (e) {
-          vscode.window.showErrorMessage(`alejandra failed: ${e}`);
-        }
+          outputChannel.appendLine(
+            `Running Alejandra with settings: ${JSON.stringify(config)}`
+          );
 
-        return;
-      }
-    })
-  );
-}
+          const process = execFile(
+            config.alejandra.program,
+            [],
+            {},
+            (error, stdout, stderr) => {
+              if (error) {
+                outputChannel.appendLine(`error: ${error}`);
+                outputChannel.appendLine(`stderr: ${stderr}`);
+                vscode.window.showErrorMessage(
+                  `While executing Alejandra with settings: ` +
+                    `${JSON.stringify(config)}, ` +
+                    `${error}`
+                );
+                reject(error);
+              }
 
-function deactivate() {}
+              const documentRange = new vscode.Range(
+                document.lineAt(0).range.start,
+                document.lineAt(
+                  document.lineCount - 1
+                ).rangeIncludingLineBreak.end
+              );
+
+              resolve([new vscode.TextEdit(documentRange, stdout)]);
+            }
+          );
+
+          const documentText = document.getText();
+
+          outputChannel.appendLine(
+            `Feeding ${documentText.length} of input to stdin`
+          );
+
+          process.stdin.write(documentText);
+          process.stdin.end();
+        } catch (error) {
+          vscode.window.showErrorMessage(
+            `While executing Alejandra with settings: ` +
+              `${JSON.stringify(config)} ` +
+              `${error}`
+          );
+          reject(error);
+        }
+      });
+    },
+  });
+};
+
+const deactivate = () => {};
 
 module.exports = {
-	activate,
-	deactivate
-}
+  activate,
+  deactivate,
+};
diff --git a/integrations/vscode/jsconfig.json b/integrations/vscode/jsconfig.json
index db5e44d..1e19ca7 100644
--- a/integrations/vscode/jsconfig.json
+++ b/integrations/vscode/jsconfig.json
@@ -1,9 +1,13 @@
 {
   "compilerOptions": {
-    "checkJs": false,
-    "lib": ["ES2020"],
-    "module": "commonjs",
+    "checkJs": true,
+    "lib": [
+      "ES2020"
+    ],
+    "module": "CommonJS",
     "target": "ES2020"
   },
-  "exclude": ["node_modules"]
+  "exclude": [
+    "node_modules"
+  ]
 }
diff --git a/integrations/vscode/package.json b/integrations/vscode/package.json
index 4df853c..36c4451 100644
--- a/integrations/vscode/package.json
+++ b/integrations/vscode/package.json
@@ -10,25 +10,40 @@
   "categories": [
     "Formatters"
   ],
-  "configuration": {
+  "contributes": {
+    "configuration": {
+      "properties": {
+        "alejandra.program": {
+          "default": "alejandra",
+          "description": "Specifies an alternative full path to the Alejandra executable.",
+          "type": [
+            "string"
+          ]
+        }
+      },
+      "title": "Alejandra"
+    },
+    "configurationDefaults": {
+      "[nix]": {
+        "editor.defaultFormatter": "kamadorueda.alejandra",
+        "editor.formatOnPaste": true,
+        "editor.formatOnSave": true,
+        "editor.formatOnType": false
+      },
+      "alejandra.program": "alejandra"
+    },
     "languages": [
       {
+        "aliases": [
+          "nix",
+          "Nix"
+        ],
         "extensions": [
           ".nix"
         ],
         "id": "nix"
       }
-    ],
-    "properties": {
-      "alejandra.program": {
-        "default": "alejandra",
-        "description": "Specifies an alternative full path to the Alejandra executable.",
-        "type": [
-          "string"
-        ]
-      }
-    },
-    "title": "Alejandra"
+    ]
   },
   "description": "The Uncompromising Nix Code Formatter",
   "devDependencies": {
@@ -45,6 +60,7 @@
   "license": "Unlicense",
   "main": "./extension.js",
   "name": "alejandra",
+  "publisher": "kamadorueda",
   "repository": {
     "type": "git",
     "url": "https://github.com/kamadorueda/alejandra"