Distributing and updating Sketch Libraries

michalk

Hi there - I'm looking for ways and examples of distributing and updating Sketch libraries for a design teams programmatically.

Currently we have a shared folder setup with all the Libraries but it's a bit of a pain to onboard new designers, not everyone is installing the libraries they need etc.

I figured out a way of programmatically installing libraries via a Sketch plugin, but then I need to distribute the library updates with a plugin update so it's like this:

1) update your plugin (using awesome appcast, thanks Sketch team!)
2) select the "Install/update Library" command to get the updated libraries

Ideally, after the libraries are installed I'd like to "point" the libraries to a remote URL for further library updates. And I'd like to users to be notified of library updates so they can choose to update or ignore the update.

Any advice, thoughts, ideas how to do that?

ivanortegaalba

michalk Why don't you try to insert the sketch file into the assets plugin folder, and using the Sketch API, you can add a library from a path. I can leave you an example:

 const libraryURL = context.plugin.urlForResourceNamed('library.sketch');
getLibraryForDocumentAtURL(libraryURL);

// This is a little modification on the Sketch API function "getLibraryForDocumentAtPath
function getLibraryForDocumentAtURL(libUrl) {
    const STATUS = {
        0: 'ok',
        1: 'the library has already been added',
        2: 'the document is not in the new JSON format',
        3: 'there was a problem reading the asset library file',
    };
    const libraryController = AppController.sharedInstance().librariesController();

    // check if we already imported the library and we remove it
    const existingLibraries = libraryController.libraries();

    for (let i = 0; i < existingLibraries.count(); i += 1) {
        const existingLibrary = existingLibraries.objectAtIndex(i);
        const location = existingLibrary.locationOnDisk();

        if (location && location.isEqual(libUrl)) {
            return fromNative(existingLibrary);
        }
    }

    // otherwise, let's add it
    const status = libraryController.addAssetLibraryAtURL(libUrl);

    if (status !== 0) {
        throw new Error(`Error while adding the library: ${STATUS[status]}.`);
    }

    const lib = libraryController.userLibraries().firstObject();

    if (!lib) {
        throw new Error('could not find the added library');
    }

    // refresh the UI
    libraryController.notifyLibraryChange(lib);

    return Library.fromNative(lib);
}

ivanortegaalba

If always is the same sketch file that you are updating in the asset folder, Sketch should recognize that the library has changed, and he'll suggest you update the symbol instances in the document.

michalk

ivanortegaalba thank, this works great thou for libraries that are part of Sketch plugin bundle.

What I'm trying to accomplish is install library from a remote URL like https://url-to-sketch-library/library.sketch and have Sketch "watch" that remote URL for any subsequent updates.

I dug up something in MSAssetLibraryController header like

@property(retain, nonatomic) NSArray *remoteLibraries; - (void)addRemoteLibraryFromAppcastURL:(id)arg1 withCompletionHandler:(CDUnknownBlockType)arg2; - (id)remoteLibraryWithAppcast:(id)arg1; - (void)downloadAssetLibraryAppcastsWithHandler:(CDUnknownBlockType)arg1 completionHandler:(CDUnknownBlockType)arg2;

it it looks like there is some API to point Sketch to remote libraries. Just do not know how to use it ?

Any tips?

mathieudutour

There is 2 different things:
- a library that is stored on the web. Then you just have to download it and add it as a local library
- a remote library for which you want to get the updates. In order to add a remote library, you need to publish an rss feed, the same way you publish an appcast.xml for plugin updates. We haven't documented it yet because the format is still changing quite a bit

ivanortegaalba

I'm distributing my library through a plugin, and I add it from the asset folder. This allows me to add foundational data like colors or typography and establish an environment with the complete design system. I'd like to open the plugin soon with all of you

By the way, thank you for the tip @mathieudutour, it's interesting to know!

cbphx

Thank you for the info @mathieudutour, the remote library is something that I am super interested in as well (similar to the Apple iOS UI templates hosted on their CDN). Any chance of beta docs for it? :-)

robin

cbphx As @mathieudutour says, be cautious as the format is liable to change.

But....here is an example RSS remote library feed from Sketch Cloud (with signatures and tokens stripped)
https://pastebin.com/raw/fRubpt3M

michalk

@robin thanks for the example, that's super interesting. Understood the RSS feed might change - 2 questions still

1) how do I get the cloud based library to show up under Preferences > Libraries with the [Download] button similar to the way Sketch integrated Apple iOS Library?

2) how should I reference the cloud based library RSS feed in manifest.json? There is an appcast entery for the plugin update RSS feed but no docs for adding a remote library RSS feed

Thanks for all the advice!

robin

michalk As I'm not Sketch team, I can only provide guesses for you ?

I think better support for adding a remote library from RSS is coming in a future Sketch release, so hang tight!

1) There are methods on the MSAssetLibraryController such as remoteLibraryWithAppcast: and - (void)addRemoteLibraryFromAppcastURL:(id)arg1 withCompletionHandler:(CDUnknownBlockType)arg2; which look like they might do what you want, but I haven't tested.

2) As far as I know, there is no support for library URLs in the plugin manifest.json

romannurik

Looks like this is formally announced in the Sketch 51 Beta:

There is now a URL protocol for adding Sketch Libraries backed by RSS feeds to Sketch

Eagerly awaiting the docs ?

mathieudutour

the url protocol is sketch-beta://add-library?url=https%3A%2F%2Frobinspeijer.nl%2Fsketch%2Fappcast (sketch-beta being the protocol for the beta, it will be sketch for the public version)

Proper documentation about all of that is coming soon

romannurik

mathieudutour Oh awesome!

It'd also be good to see an example use of addRemoteLibraryFromAppcastURL_withCompletionHandler to achieve this from a plugin ?

mathieudutour

you can have a look here: https://github.com/BohemianCoding/SketchAPI/blob/develop/Source/dom/components/Library.js#L81-L108 but it's not finished yet (Sketch crashes when cleaning up the block, I need to spend more time on it)

romannurik

mathieudutour whoa, looks like we can use blocks now as of Sketch 51?

__mocha__.createBlock_function

mathieudutour

yeah but I wouldn't recommend it yet, as I said, there are some memory management issues somewhere

Ashung

mathieudutour it works.

NSWorkspace.sharedWorkspace().openURL(NSURL.URLWithString("sketch-beta://add-library?url=http%3A%2F%2F127.0.0.1:8000%2Fappcast.xml"));

romannurik

mathieudutour any chance the final Sketch 51 works better with this?

mathieudutour

Ashung yes that works but you won't know when the library is added (since it's asynchronous)

romannurik

Ashung that's a good workaround for now, though I wish there was a Sketch 50-friendly version :-/