dnscontrol/documentation/typescript.md
Paul Dee 731181ffa1
DOCS: Mostly styling and links (#2178)
Co-authored-by: Tom Limoncelli <tal@whatexit.org>
2023-03-15 18:43:57 -04:00

2.7 KiB
Raw Blame History

Using TypeScript with DNSControl (experimental)

What is this?

Would you like your editor to support auto-completion and other advanced IDE features when editing dnsconfig.js? Yes you can!

While DNSControl does not support TypeScript syntax in dnsconfig.js, you can still use TypeScripts features in editors which support it.

If youre using Visual Studio Code (or another editor that supports TypeScript), you should now be able to see the type information in your dnsconfig.js file as you type. Hover over record names to read their documentation without having to open the documentation website!

How to activate auto-completion

To set up TypeScript support in Visual Studio Code, follow these steps:

  1. Run this command to generate the file types-dnscontrol.d.ts.
dnscontrol write-types

This file has all the information your editor or IDE needs. It must be in the same directory as the dnsconfig.js file you are editing.

NOTE: Re-run the dnscontrol write-types command any time you upgrade DNSControl. Because it is generated from the command, it will always be correct for the version of DNSControl you are using.

  1. Tell your editor

At this point some features (autocomplete) will work. However to get the full experience, including type checking (i.e. red squiggly underlines when you misuse APIs), there is one more step.

Add this comment to the top of your dnsconfig.js file:

{% code title="dnsconfig.js" %}

// @ts-check

{% endcode %}

That should be all you need to do!

If your editor requires extra steps, please file a bug and we'll update this page.

Bugs?

Bugs? Not all features of DNSControl work perfectly at the moment. Please report bugs and feature requests on https://github.com/StackExchange/dnscontrol/issues

This is experimental. This feature is currently experimental. We might change the installation instructions as we find better ways to enable this.

Known bugs

Bug: CLI_DEFAULTS not implemented

Bug: Values passed to CLI_DEFAULTS (and the corresponding -v command-line option) dont show up as global variables

Workaround: create a new .d.ts file in the same folder as your dnsconfig.js file. In that file, add the following line for each variable you want to use (replacing VARIABLE_NAME with the name of the variable).

{% code title=".d.ts" %}

declare const VARIABLE_NAME: string;

{% endcode %}

This will tell TypeScript that the variable exists, and that its a string.

Known issue: FETCH not always accurate

Bug: FETCH is always shown as available, even if you dont run DNSControl with the --allow-fetch flag.