What typescript feature allows GenericSlide to gain more properties as you import more plugins?

[minijoo]

I was struggling with finding "title" and "description" properties to show up in a file where I'm building SlideImage. I noticed the properties were defined in the plugins/caption/index.d.ts so I tried ES6 importing the Captions plugin and the "title" "description" properties showed up. I moved the Captions plugin import to a different file (where the Lightbox is actually used) and it still worked!!

What typescript feature allows for this? I'm a beginner typescript user and interested in learning more about it but I can't seem to find the exact googleable words.

[igordanchenko]

Hi @minijoo,

Great question! The behavior you're seeing, where the GenericSlide type gains properties like title and description when you import the Captions plugin, is due to a TypeScript feature called module augmentation combined with declaration merging.

What's Happening?

In the yet-another-react-lightbox library, the GenericSlide type is designed to be extensible. When you import the Captions plugin (e.g., import Captions from "yet-another-react-lightbox/plugins/captions"), the plugin's type definition file (index.d.ts) augments the GenericSlide interface to include additional properties like title and description. This allows the type system to recognize these properties on your slides without requiring you to manually extend the type.

The TypeScript Features Involved

1. Declaration Merging:

• TypeScript allows multiple declarations of the same interface to be "merged" into a single definition. In this case, the GenericSlide interface is declared in the core library, and the Captions plugin adds its own properties (title and description) to the same interface.
• This is possible because TypeScript merges interface declarations with the same name in the same module scope.

Module Augmentation:

• When you import the Captions plugin, its type definition file modifies the GenericSlide interface defined in the core yet-another-react-lightbox module. This is done using TypeScript's module augmentation, which allows a module to extend the types of another module.
• In the plugins/captions/index.d.ts file, there's a declaration like this:

declare module "yet-another-react-lightbox" {
  interface GenericSlide {
    title?: React.ReactNode;
    description?: React.ReactNode;
  }
}

This code tells TypeScript to extend the GenericSlide interface in the yet-another-react-lightbox module, adding the title and description properties.

Why It Works Across Files:

• You noticed that importing the Captions plugin in one file makes the properties available in another file. This is because module augmentation is a global operation within your project's TypeScript compilation context. Once the plugin's type definitions are included in your project (via the import), TypeScript applies the augmented GenericSlide interface everywhere the yet-another-react-lightbox module is used.

Why Is This Cool?

This design makes the library highly extensible and type-safe. Each plugin can add its own properties to GenericSlide without modifying the core library's code. As a user, you get automatic type support for plugin-specific features just by importing the plugin, and TypeScript ensures you use those properties correctly.

Learning More

To dive deeper into these TypeScript features, here are some googleable terms and resources:

• TypeScript Declaration Merging: Learn how TypeScript combines multiple interface declarations.
  • TypeScript Handbook: Declaration Merging
• TypeScript Module Augmentation: Understand how to extend types in external modules.
  • TypeScript Handbook: Module Augmentation
• TypeScript Plugins Pattern: Search for "TypeScript extensible types with plugins" to see how libraries like this one structure their types.

If you're curious about the exact implementation, you can check the index.d.ts file in the plugins/captions directory of the yet-another-react-lightbox repository to see how the augmentation is written.

Hope this helps clarify things!