• Home
  • Blog
  • Projects
  • Bookshelf
  • About
← Back to all posts

Quick Tip - Specific Local Module Declarations

Published ....
Last modified ....

Share this post on BlueskySee discussion on Bluesky


I've been working in a codebase lately that uses a shared module across a few different files - in my case the module is a JSON file that I'm importing and I wanted to enforce consistent types for the value when it was imported across the codebase.

As far as I can tell the recommended solution looked something like this:

import jsonObject from "./some/path/to/the/file.json";
import type { MyDesiredJSONType } from "./some-types";

let 
actualValue
=
jsonObject
as
MyDesiredJSONType
;

It felt a bit icky to me to not only copy and paste that across the codebase, but also worry about trying to remind others contributing to the code to do the same thing when they want to import the JSON value.

I instead found a neat little alternative approach that works pretty well, using module declarations and import maps (I've written about import maps before in this blog post)!

The trick is to do the following:

  • Create a local <some-filename>.d.ts file (I've opted to call mine local-types.d.ts since I have a few other things in there too)
  • Add the following content to the file:
declare module "#<some-identifier>" {
  import type { MyDesiredJSONType } from "./src/types";
  let jsonObject: MyDesiredJSONType;
  export default jsonObject;
}

I recommend prefixing the identifier with a special character, specifically #. This helps to identify it as a local module specifier (as opposed to @ which might map to a scoped 3rd party package), and easily stands out to others reading the codebase!

Finally, and importantly, configure your import maps / paths configs:

  • For Node.js / other node-like tools:
    • Add a new mapping to your package.json imports record
  • For TypeScript:
    • Add a new mapping to your tsconfig.json paths record

Here's an example configuration within a package.json file:

{
  "imports": {
    "#some-identifier": "./src/some-json-file.json"
  }
}

and here's an example configuration within a tsconfig.json file:

{
  "compilerOptions": {
    "paths": {
      "#some-identifier": ["./src/some-json-file.json"]
    }
  }
}

Note! Just because I'm using a JSON module as an example here doesn't mean this strategy only works with JSON files - you can do this for any kind of file type!

Thats it! This should then let TypeScript use that declared module type whenever you import from this new identifier!


Tags:

TypeScriptWeb DevelopmentTipDevelopmentNode.js

Bluesky Post and Comments:

Loading comments...

Loading...

Related Posts

TypeScript

Async Class Creation In JavaScript

....

Have you ever wanted to create a class in JavaScript or TypeScript but also have the initialization be async? Here's a quick tip on a pattern that I've used in the past!

The Bookkeeping Pattern

....

A quick look at a small but powerful pattern I've been leveraging as of late!

TSLite

....

A proposal for a minimal variant of TypeScript!

Hohoro

....

A quick introduction to my new side project, hohoro. An incremental JS/TS library build tool!

Web Development

Website Redesign v11

....

I've once again updated my personal website, this time powered by my own RSC framework and a custom CMS solution as well!

Onboarding Your New AI Teammate

....

Are we reinventing the wheel when it comes to onboarding new AI agents to a codebase, when we already have primitives available for onboarding humans?

Quick Tip - Theme Aware Images

....

Tip

Quick-Tip: Codex Chief of Staff Thread

....

Tip: Secrets for Cloudflare Workers

....

Tip: GitHub Created Date Filtering

....

Development

Website Redesign v11

....

I've once again updated my personal website, this time powered by my own RSC framework and a custom CMS solution as well!

Onboarding Your New AI Teammate

....

Are we reinventing the wheel when it comes to onboarding new AI agents to a codebase, when we already have primitives available for onboarding humans?

Tip: GitHub Created Date Filtering

....

Node.js

A Quick Look at Import Maps

....

A brief look at Import Maps and package.json#imports to support isomorphic JavaScript applications!

Have you ever found the need to change the image you render on a web page based on the current preferred color scheme of your theme?

Async Class Creation In JavaScript

....

Have you ever wanted to create a class in JavaScript or TypeScript but also have the initialization be async? Here's a quick tip on a pattern that I've used in the past!

Website Redesign v10

....

I recently launched a rewrite and redesign of this personal website, I figured I'd talk a bit about the changes and new features that I added along the way!

Server Side Rendering Compatible CSS Theming

....

A quick tip to implementing CSS theming that's compatible with Server Side Rendered applications!

Podcasting By Hand

....

A brief overview on how we launched The Bikeshed Podcast, including a deep dive in our recording and distribution workflows!

On File-System Routing Conventions

....

Some rough thoughts on building a file-system routing based web application

You're Building Software Wrong

....

Slicing software: why vertical is better than horizontal.

Single File Web Apps

....

What if you could author an entire web application in a single file?

Resetting Controlled Components in Forms

....

A quick way to handle resetting internal state in components when a parent form is submitted!

A Quick Look at Import Maps

....

A brief look at Import Maps and package.json#imports to support isomorphic JavaScript applications!

Recommended Tech Talks

....

A collection of tech talks that I regularly re-watch and also recommend to everyone!

Request for a (minimal) RSC Framework

....

Some features and functionality that I'd like within a React Server Component compatible framework.

Bluesky Tips and Tools

....

A (running) collection of Bluesky tips, tools, packages, and other misc things!

The Bookkeeping Pattern

....

A quick look at a small but powerful pattern I've been leveraging as of late!

TSLite

....

A proposal for a minimal variant of TypeScript!

Monorepo Tips and Tricks

....

Sharing a few core recommendations when working within monorepos to make your life easier!

Next.js with Deno v2

....

This is a quick post noting that Next.js should now work with Deno v2!

Don't Break the Implicit Prop Contract

....

React components have a fundamental contract that is often unstated in their implementation, and you should know about it!

A Better useSSR Implementation

....

Replace that old useState and useEffect combo for a new and better option!

My Current Dev Setup

....

A quick look at the applications and tools that I (generally) use day to day for web development!

Abstract Your API

....

Proposing a solution for sharing core "business" logic across services!

Tip: Request and Response Headers

....

There's a common gotcha when creating Web Request and Response instances with Headers!

Using Feature Toggles to De-risk Refactors

....

Feature toggles are often underused by most software development teams, and yet offer so much value during not only feature development but also refactors

Hohoro

....

A quick introduction to my new side project, hohoro. An incremental JS/TS library build tool!

Custom Favicon Recipes

....

Two neat tricks for enhancing your site's favicon!

Corporate Sponsored OSS

....

The various risks and pitfalls of open source software run by corporations.

The Library-Docs Monorepo Template

....

A monorepo template for managing a library and documentation together.

Building Better Beacon

....

How we solved an almost show-stopping production bug, and how you can avoid it in your own projects.

Project Deep Dive: Tails

....

A(nother) deep dive into one of my recent side projects; tails - a plain and simple cocktail recipe app.

Churn Anxiety

....

When did semver major changes become so scary?

Service Monitors and Observability

....

Leveraging service monitors properly to improve service observability.

On Adopting CSS-in-JS

....

A brief recap of how Wayfair changed it's CSS approach not once but twice in the span of 5 years!

Project Deep Dive: Microfibre

....

A deep dive into one of my recent side projects; microfibre - a minimal text posting application

Pair Programming

....

Pair programming can be good sometimes - but not all the time

Suspense Plus GraphQL

....

A few thoughts on using Suspense with GraphQL to optimize application data loading

You've Launched, Now What?

....

A few thoughts on what to do after you launch a new project

Taking a Break

....

A few quick thoughts on burn out and taking a break

Managing Complex UI Component State

....

A few thoughts on managing complex UI component state within React

Understanding React 16.3 Updates

....

A quick overview of the new lifecycle methods introduced in React 16.3

CSS in JS

....

A few thoughts and patterns for using styled-jsx or other CSS-in-JS solutions

Redesign v6

....

A few thoughts on the redesign of my personal site, adopting Next.js and deploying via Now

JavaScript Weirdness

....

A few weird things about JavaScript

Calendar

....

Building a calendar web application

Roundup Notes in Obsidian with Dataview

....

A quick tip for creating roundup or summary notes based on other notes in Obsidian using the Dataview plugin!

Quick Tip - Theme Aware Images

....

Have you ever found the need to change the image you render on a web page based on the current preferred color scheme of your theme?

Async Class Creation In JavaScript

....

Have you ever wanted to create a class in JavaScript or TypeScript but also have the initialization be async? Here's a quick tip on a pattern that I've used in the past!

Server Side Rendering Compatible CSS Theming

....

A quick tip to implementing CSS theming that's compatible with Server Side Rendered applications!

Replacing Dropbox Capture with Raycast

....

Recently Dropbox announced that it was shutting down the Capture app/service, so I sought out an alternative that provided a similar user experience!

Bluesky Tips and Tools

....

A (running) collection of Bluesky tips, tools, packages, and other misc things!

The Bookkeeping Pattern

....

A quick look at a small but powerful pattern I've been leveraging as of late!

Don't Break the Implicit Prop Contract

....

React components have a fundamental contract that is often unstated in their implementation, and you should know about it!

A Better useSSR Implementation

....

Replace that old useState and useEffect combo for a new and better option!

Tip: Request and Response Headers

....

There's a common gotcha when creating Web Request and Response instances with Headers!

Exporting Custom Slack Emoji

....

How to easily mass-export your custom slack emoji without API access!

Custom Favicon Recipes

....

Two neat tricks for enhancing your site's favicon!

Fixing Zed's language server

....

Zed language server quick tip; fixing Zed's language server

Progressive Identifiers

....

Roundup Notes in Obsidian with Dataview

....

A quick tip for creating roundup or summary notes based on other notes in Obsidian using the Dataview plugin!

Quick Tip - Theme Aware Images

....

Have you ever found the need to change the image you render on a web page based on the current preferred color scheme of your theme?

Website Redesign v10

....

I recently launched a rewrite and redesign of this personal website, I figured I'd talk a bit about the changes and new features that I added along the way!

You're Building Software Wrong

....

Slicing software: why vertical is better than horizontal.

Single File Web Apps

....

What if you could author an entire web application in a single file?

The AI Development Conundrum

....

Is it a good or a bad thing to offload writing code to AI agents and Large Language Models?

A Quick Look at Import Maps

....

A brief look at Import Maps and package.json#imports to support isomorphic JavaScript applications!

Recommended Tech Talks

....

A collection of tech talks that I regularly re-watch and also recommend to everyone!

Request for a (minimal) RSC Framework

....

Some features and functionality that I'd like within a React Server Component compatible framework.

Bluesky Tips and Tools

....

A (running) collection of Bluesky tips, tools, packages, and other misc things!

Building a Custom Ghostty Theme

....

How to generate a custom Ghostty theme based on any iterm2 theme!

Offload Complexity, Don't Offload Learning

....

A rough mental model for how you should be leveraging AI as a tool for your own growth

More Thoughts on Dogfooding

....

Even more thoughts on dogfooding!

Dogfooding

....

The secret to excellent product teams is using your own product, and often!

Git Notes as a Tool for Thought

....

(Ab)using Git as yet another tool for thought!

My Current Dev Setup

....

A quick look at the applications and tools that I (generally) use day to day for web development!

Tip: Request and Response Headers

....

There's a common gotcha when creating Web Request and Response instances with Headers!

Using Feature Toggles to De-risk Refactors

....

Feature toggles are often underused by most software development teams, and yet offer so much value during not only feature development but also refactors

Hohoro

....

A quick introduction to my new side project, hohoro. An incremental JS/TS library build tool!

Funport: True Dynamic Imports in webpack

....

webpack, and tools built on it like Next.js, don't support true dynamic imports, but I found a way to trick the system!

My Current AI Stack

....

I've been using a variety of AI tools as of late, I figured I'd document the ones I'm primarily using!

Configuring Cloudflare Domains with Vercel

....

I've started to use Cloudflare to manage my domains for several side projects, have had to jump through the same hooks multiple times that I figured I should document them here!

React Error Boundaries: Revisited

....

Revising my previous blog post on React Error Boundaries and my preferred go-to implementation!

Custom Favicon Recipes

....

Two neat tricks for enhancing your site's favicon!

Corporate Sponsored OSS

....

The various risks and pitfalls of open source software run by corporations.

The Library-Docs Monorepo Template

....

A monorepo template for managing a library and documentation together.

Building Better Beacon

....

How we solved an almost show-stopping production bug, and how you can avoid it in your own projects.

Churn Anxiety

....

When did semver major changes become so scary?

Stop Snacking

....

No I don't mean those Milano cookies you keep taking from the office snack wall either (although you should probably stop snacking on those as often as well).

Pair Programming

....

Pair programming can be good sometimes - but not all the time

Taking a Break

....

A few quick thoughts on burn out and taking a break

Matt Hamlin

Matt Hamlin

@matthamlin.me

Quick Tip - Specific Local Module Declarations: matthamlin.me/blog/2025/fe...
Quick Tip - Specific Local Module Declarations

Quick Tip - Specific Local Module Declarations

A quick tip outlining how to provide specific TypeScript type definitions for a local module!

https://matthamlin.me/blog/2025/february/quick-tip-specific-local-module-definitions
1 year agoView on bsky.app
0
1
0
0