TypeScript definitions

[seebeen]

Hello, I've just been introduced to Alpine.js - and I love it.

The only problem I currently have is that it has no Typescript definition files, and I write primarily TS.
I'm 100% sure that I am not the only one - so my main question is:

Is there a plan to create .d.ts files for Alpine?

[danddanddand]

We have a v3 definition we use locally so I can see about having it added through PR if there is other interest. It's not complete but here is rough draft of our current one:

our internal alpine.d.ts

type AlpineWatch = ( targetProperty: string, callback: ( ( newValue: any, oldValue?: any ) => void ) ) => void;

type AlpineMagicProperties<AlpineGlobalStore = Record<string, V>> = {
    $el?: HTMLElement;
    $refs?: { [xRefId: string]: HTMLElement };
    $watch?: AlpineWatch;
    $nextTick?: ( functionToCall: ( () => void ) ) => void;
    $store?: AlpineGlobalStore;
    $dispatch?: <T = any>( eventName: string, eventDetail?: T ) => void;
};

type AlpineMandatoryProps = {
    init?: () => void,
}

declare type AlpineComponent<Props extends BaseAlpineProps, AlpineGlobalStore = {}> = {
    (): AlpineMandatoryProps & Props & AlpineMagicProperties<AlpineGlobalStore>;
};

interface BaseAlpineProps {
    init?: ( () => void ) | ( () => Promise<void> );
}

interface AlpineRoot {
    store,
    start,
    directive,
    version: string,
}

declare module "alpinejs" {
    type AlpineDirectiveCallback = ( p1 : HTMLElement, p2 : any, p3: any ) => void;
    type AlpineRootCallback = ( ( alpineRoot : Alpine ) => void );
    function store<R>( storeName: string, value : R ) : void;
    function store<R>( storeName: string ) : R;
    function directive( directiveName : string, cb : AlpineDirectiveCallback );
    function plugin( alpineRootCallBack : AlpineRootCallback ) : void;
    function data( dataName: string, dataInitializer: () => Record<string, V> ): void;
    function effect( effectCallback: () => void ): void;
    function reactive<T>( initialData: Record<string, T> ): Record<string, T>;
    function magic( magicName: string, callback: ( el: HTMLElement, alpineObj: { Alpine: Alpine } ) => any ): void;
    function start() : void;

    export default Alpine = {
        version: string,
        store,
        start,
        directive,
        plugin,
        data,
        effect,
        reactive,
        magic
    };

}

[RubenBimmel]

Nice one! I'd love to see these added as well!

[seebeen]

Looks good as a starting point. Would you have anything against me writing a (semi)official @types/alpine definition?

Also, (and I know I'm being biased), are there any plans to rewrite Alpine in TS?

[danddanddand]

Looks good as a starting point. Would you have anything against me writing a (semi)official @types/alpine definition?

Also, (and I know I'm being biased), are there any plans to rewrite Alpine in TS?

@seebeen Since Caleb is open to it being maintained here that would be best way to do it. (I'm fine with definitely typed too but definitions would drift less if maintained here). If you want to post your updated version here I'll see how they work in our codebase which is a large project and we can iterate on it until ready for a formal PR.

[seebeen]

type AlpineWatch = ( targetProperty: string, callback: ( ( newValue: any, oldValue?: any ) => void ) ) => void;

type AlpineMagicProperties<AlpineGlobalStore = Record<string, V>> = {
    $el?: HTMLElement;
    $refs?: { [xRefId: string]: HTMLElement };
    $watch?: AlpineWatch;
    $nextTick?: ( functionToCall: ( () => void ) ) => void;
    $store?: AlpineGlobalStore;
    $dispatch?: <T = any>( eventName: string, eventDetail?: T ) => void;
};

type AlpineMandatoryProps = {
    init?: () => void,
}

declare type AlpineComponent<Props extends BaseAlpineProps, AlpineGlobalStore = {}> = {
    (): AlpineMandatoryProps & Props & AlpineMagicProperties<AlpineGlobalStore>;
};

interface BaseAlpineProps {
    init?: ( () => void ) | ( () => Promise<void> );
}

interface AlpineRoot {
    store,
    start,
    directive,
    version: string,
}

declare module "alpinejs" {
    type AlpineDirectiveCallback = ( p1 : HTMLElement, p2 : any, p3: any ) => void;
    type AlpineRootCallback = ( ( alpineRoot : Alpine ) => void );
    function store<R>( storeName: string, value : R ) : void;
    function store<R>( storeName: string ) : R;
    function directive( directiveName : string, cb : AlpineDirectiveCallback );
    function plugin( alpineRootCallBack : AlpineRootCallback ) : void;
    function data( dataName: string, dataInitializer: () => Record<string, V> ): void;
    function effect( effectCallback: () => void ): void;
    function reactive<T>( initialData: Record<string, T> ): Record<string, T>;
    function magic( magicName: string, callback: ( el: HTMLElement, alpineObj: { Alpine: Alpine } ) => any ): void;
    function start() : void;

    export default Alpine = {
        version: string,
        store,
        start,
        directive,
        plugin,
        data,
        effect,
        reactive,
        magic
    };

}

Adding the definition you added with proper syntax highlighting

[danddanddand]

Okay. That's really rough draft ever changing in our company so just warning it's not very fleshed out but more of starting place

[calebporzio]

Good question. No plans to rewrite in TS. (I know everyone unanimously loves it, I just really like plain JS)

However, I'm definitely open to adding TS definitions. Because we would have to keep it in sync with core and maintain it long term, I'd like for this to be refined by the community and then when there's sufficient demand, we can pull it into core.

Maybe this is the best place to gauge that interest and hold that discussion. Thanks again!

[JoshStrobl]

Just want to mention (as part of that whole "gauge that interest") that I would love for there to be TypeScript definitions for Alpine and while I am a bit rusty with actually writing them (have done so in the past with DefinitelyTyped), would be happy to work alongside others like @seebeen to help maintain it.

[danddanddand]

@JoshStrobl I'm pretty far along on a project to add a PR for the TS definitions. I was basically planning on maintaining a TS fork of Alpine just to generate the .d.ts files automatically. It's small side project for me and I have a lot of vacation time scheduled, so I'm not sure I'll be fast on. Just a heads up that someone is working on it.

For my project our dev team has been iterating on a "good enough" version similar to what's posted here.