Electron-builder: Feature request: programmatic API

[adam-lynch]

That would be nice :grinning:

[develar]

We already have programmatic API :)

[ErikBean]

I would really like to see this issue reopened. According to the README I should look at node_modules/electron-builder/out/electron-builder.d.ts. Anyone wanting to use electron-builder programmatically is required to clone the project, run a compile script to generate /out, which contains a TypeScript file. I would like to use/improve this, but I have zero TypeScript experience, and it seems unnecessary to force people to learn TS in order to use this API. Just my 2 cents.

[adam-lynch]

Erik, you're wrong as far as I remember. If you install from npm, the files
should be generated, but not if installing from GitHub. I think anyway.

On Thu, Mar 24, 2016, 22:15 Erik Bean [email protected] wrote:

I would really like to see this issue reopened. According to the README I
should look at node_modules/electron-builder/out/electron-builder.d.ts.
Anyone wanting to use electron-builder programmatically is required to
clone the project, run a compile script to generate /out, which contains a
TypeScript file. I would like to use/improve this, but I have zero
TypeScript experience, and it seems unnecessary to force people to learn TS
in order to use this API. Just my 2 cents.

—
You are receiving this because you authored the thread.
Reply to this email directly or view it on GitHub
https://github.com/electron-userland/electron-builder/issues/156#issuecomment-201047422

[develar]

@ErikBean electron-builder.d.ts only for external usage. This file exist when module is installed.

unnecessary to force people to learn TS in order to use this API

Why you are forced?

declare module 'electron-builder/out/awaiter' means that you need to require("electron-builder/out/awaiter") to use members from this module.

Syntax in the d.t.s is the same as ES6 (there are some differences (additions to syntax), but not major).
Why it is not documented in some popular format — JSDoc for example? Because I don't have time.

I would like to use/improve this

If you want to improve and change existing code, TS is not a show-stopper, because it is a ES6 + types. Nothing more. It is not modern language like Kotlin. It is old outdated JavaScript. Nothing new and modern.

You don't need even to change your workflow — if you don't want to use IDE to comfortable edit and compile code — just use ts-node.

Want to see detailed docs how to use ts-node? Just ask and it will be prepared (WebStorm has excellent TS support and, so, I don't use ts-node). Atom also supports TS (but I recommend to use WebStorm (again — it is not required and you can just use ts-node for development)).

[ErikBean]

Just seems misleading to advertise a programmatic API in the README is all.

On Thu, Mar 24, 2016 at 11:19 PM, Vladimir Krivosheev <
[email protected]> wrote:

@ErikBean https://github.com/ErikBean electron-builder.d.ts only for
external usage. This file exist when module is installed.

unnecessary to force people to learn TS in order to use this API

Why you are forced?

declare module 'electron-builder/out/awaiter' means that you need to
require("electron-builder/out/awaiter") to use members from this module.

Syntax in the d.t.s is the same as ES6 (there are some differences
(additions to syntax), but not major).
Why it is not documented in some popular format — JSDoc for example?
Because I don't have time.

I would like to use/improve this
If you want to improve and change existing code, TS is not a show-stopper,
because it is a ES6 + types. Nothing more. It is not modern language like
Kotlin. It is old outdated JavaScript. Nothing new and modern.

You don't need even to change your workflow — if you don't want to use IDE
to comfortable edit and compile code — just use ts-node
https://github.com/TypeStrong/ts-node.

Want to see detailed docs how to use ts-node? Just ask and it will be
prepared (WebStorm has excellent TS support and, so, I don't use ts-node).
Atom http://atom%20ts%20node also supports TS (but I recommend to use
WebStorm (again — it is not required and you can just use ts-node for
development)).

—
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub
https://github.com/electron-userland/electron-builder/issues/156#issuecomment-201160189

[develar]

@ErikBean I will try to fix doc somehow.

If something stops you — feel free to ask me about it.

[sohilnandu]

@develar Hello, I'm upgrading from the old electron-builder version 2.7.1 and was using the programmatic api.

I'm a bit confused with the new api and lack of documentation. I'm not familiar with typescript. Can you provide a very basic example please.

This is what I was previously doing:

var builder = require('electron-builder');

var options = {
    platform: 'osx',
    out: 'release/osx',
    config: config,
    appPath: 'release/osx/Application.app,
    basePath: '.'
};

// create the installer
var electronBuilder = builder.init();
electronBuilder.build(options, function(){
    // other stuff here
});

Thanks in advance for your help!

[develar]

@sohilnandu Docs fixed, please see https://github.com/electron-userland/electron-builder#programmatic-usage

[sohilnandu]

@develar Thanks, appreciate it!

[framerate]

Hey guys -

I'm new to this project and finding the linked docs rather confusing. For example, in the typescript file node_modules/electron-builder/out/electron-builder.d.ts I see that there are options like:

appDir?: string | null
projectDir?: string | null

but as someone learning electron I don't know which is which. I'm assuming one is the output and one is the directory of my pre-packaged electron-packager file. But it also could be that electron-builder is meant to replace electron-packager which I'm unsure since most tutorials list packager for building and builder for "packaging" the installer (strange...).

Is there somewhere else where these parameters for programmatic stuff is documented that I'm missing? And if so I'd be more than happy to edit the readme when I'm done figuring this all out...

Thanks!

EDIT: I should add that my goal here is to take a functional OSX/Windows app and package it into an installer and get auto updating working. That is what drew me to this project.

[develar]

appDir and projectDir — see https://github.com/electron-userland/electron-builder#two-packagejson-structure

• You should not set it explicitly. Just follow conventions. Name app dir as app.
• If you use one-project project structure — appDir equals to projectDir (where your package.json located).

FYI: appDir?: string | null — ? question here means that field is optional and you don't need to specify it.

my goal here is to take a functional OSX/Windows app and package it into an installer and get auto updating working. That is what drew me to this project.

Please avoid programmatic usage. Consider to use npm scripts. If something force you to use programmatic API — feel free to report and we maybe suggest some smart solution.

[framerate]

Thanks for the reply.

Please avoid programmatic usage. Consider to use npm scripts. If something force you to use programmatic API — feel free to report and we maybe suggest some smart solution.

This seems odd because it's sort of documented in your readme. If you feel this way, I'd suggest removing it from the docs. If not, It'd be great to see the docs improved to make it usable. In the state it is now, it's just confusing :/

I wanted to use programatic so I could control what was happening a little more. I know it's mentioned in the readme, but it's still rather confusing for me to see:

        "pack": "build",
        "dist": "build",

in my scripts. Plus when I was hitting a bug with signing my app (I reported it but it ended up being an XCode problem... but it was so vague I had no way of knowing) electron-builder was just a black box I was putting variables into. I was hoping to use programmatic integration so that I had a better handling of what was happening instead of just resting my entire app that your black box would work (especially when it wasn't!)

If you'd like I can submit a PR that at least adds

Please avoid programmatic usage. Consider to use npm scripts. If something force you to use programmatic API — feel free to report and we maybe suggest some smart solution.

to the programmatic section if you'd like people to avoid it?

[sohilnandu]

I agree, I was also pretty confused.

Also, what's the reasoning behind avoiding programmatic usage?

I prefer using programmatic API's over a CLI when scripting. In fact I'm sticking with the old version of this library before it was merged with electron-complete-builder. I would love to take advantage of all the improvements, including app signing, but this version just doesn't meet my build process needs.

In my particular case, I use gulp tasks to do a lot of preprocessing (minify, uglify, etc.) before packaging my app. It would be ideal for me to programmatically call electron-builder from gulp once my preprocessing is done.

[develar]

Programmatic usage doesn't transform black box to something clear. Each level of abstraction is a black box. Even if you work on very low level — exec codesign directly, it will be still a black box. Because you have to know in this case how SSL/signing work.

It is exactly why this tool was born — to marry all existing tools and provide complete seamless solution. E.g. all win tools suck and has low quality/bad design.

What we should do in your case — check such code sign error and show user-friendly error message.

If you use gulp — yes, it is valid reason to use programmatic API.

[vicentedealencar]

If you use gulp there is still a way to avoid the api

  "dist": "gulp && build"

[develar]

@vicentedealencar Exactly. e.g. I use in my project "dist": "npm run compile && build",.