webextension-toolbox / generator-web-extension

Advanced WebExtension generator that creates everything you need to get started with cross-browser web-extension development.

Generator: WebExtension

Advanced WebExtension generator that creates everything you need to get started with cross-browser extension/addon development.

Under the hood it uses webextension-toolbox for compiling the extensions.

Install

$ npm install -g yo generator-web-extension

Getting Started

1. First make a new directory, and cd into it: mkdir my-web-extension && cd $_
2. Run: yo web-extension.

Options

• --skip-install

  Skips the automatic execution of npm after scaffolding has finished.

License

Copyright 2018 Henrik Wenz

This project is free software released under the MIT license.

generator-web-extension's Issues

Demo screenshot

Create a demo screenshot.gif.

https://asciinema.org/

[Windows] Unhandled promise rejection Error: absolute path (.../scripts/background.js)

I'm running into issues building a chrome extension.

Environment:

• [email protected]
• [email protected]
• [email protected]
• Windows 10 64bit

Steps to reproduce:

1. mkdir D:/test && cd $_
2. yo web-extension
   • Default name, short_name, and description
   • Browser UI Action
   • No overrides
   • No more UI features
   • No permissions
   • Yes for promo images
3. npm install
4. npm run build chrome

Expected result:
A populated dist/ folder with the chrome extension content.

Actual result:

$ npm run build chrome

> [email protected] build D:\test
> webextension-toolbox build "chrome"

clean-webpack-plugin: D:\test\dist\chrome has been removed.
(node:16360) UnhandledPromiseRejectionWarning: Unhandled promise rejection (rejection id: 1): Error: absolute path: D:/test/app/scripts/background.js
(node:16360) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.

Feature Request: eject ala create-react-app

First big kudos! I love this generator and how easy it makes it to get started with a web extension, so thanks a lot!

The main problems I have with it are flexibility and lock-in.

When you start needing to customize your build setup and diverge from the sensible startup defaults provided, the single dependency on webextension-toolbox can run you into roadblocks.

Another very popular scaffold tool that took a similar approach is Facebook's create-react-app, which implements the same pattern of depending on a single package (react-scripts) to abstract away a sensible default build config.

They solve both the lock-in/customization problems with a pretty elegant solution: their eject feature, which basically copies back the whole build config from the react-scripts package into your own project so you can move forward, customize and maintain your own build config without having to fork the build tool. I feel it's a really important feature to have for any scaffolding tool taking the separate-package-for-build approach.

I see that webextension-toolbox has taken a different road with webextension-toolbox.js, which is a good middle of the road approach if your customization needs involve the webpack config (likely the most common use-case). Actually both solutions are compatible and can be complementary, as the custom webpack config can push the point where you'll need to run your own build config further into the future. But it doesn't give you nearly the same amount of flexibility and it doesn't solve lock-in. You're still heavily dependent on webextension-toolbox being actively maintained, say to upgrade the libraries, and if your setup ever diverges enough from the toolbox' sensitive defaults (which may not be so sensitive or in touch with the industry's common practices 2 years from now in the fast evolving frontend ecosystem), you're left with no easy migration path.

Their eject script doesn't look that complicated, though of course building one requires in-depth familiarity with the tool being "ejected", its structure, conventions and quirks.

So I just thought I'd take a shot at suggesting the idea here :) It's a bit of work but it has potential to be a solution to a lot of future configuration/customization requests, and reduce the lock-in burden for both users and maintainers.

Additonal Loaders

Hi,

I'm trying to use Vue js with this, but where can I add my loader for .vue components for webpack?

Question: how does this package handle differences between W3C and Chrome implementations

I'll keep this brief. Please refer to the respective sections of Chrome and Moz websites on type StorageArea.

While W3C Draft (moz) specifies get and set calls as Iterable (Promises) — Chrome uses a callback to deliver the results.

This would not work in Chrome at the moment:

async function amendStorage(key: string, new_data: Object): void {
    let current_data = await browser.storage.sync.get(key);
    browser.storage.sync.set({
        [key]: {
            ...current_data[key],
            new_data
        }
    )
    .then((u) => {
        console.info(`Storage has been updated. Now: ${JSON.stringify(u)}`)
    });
}

— because typeof current_data is 'undefined', as the value returned by StorageArea.set (and get) in latest consumer Chrome.

I've not tested the extension code from this generator outside Chrome, but I am curious to know what happens in other big browsers supporting the W3C draft (Firefox, Opera, Edge), if the code is written using Chrome's callback-style. I assume it will crash.

npm run build chrome - WebpackOptionsValidationError:

After running successfully

yo web-extension

I got the folowing error when running

npm run build chrome

[email protected] build /home/XXX/XXX/chrome/wallext
 webextension-toolbox build "chrome"

/home/XXX/XXX/chrome/wallext/node_modules/webpack/lib/webpack.js:19
		throw new WebpackOptionsValidationError(webpackOptionsValidationErrors);
		^

WebpackOptionsValidationError: Invalid configuration object. Webpack has been initialised using a configuration object that does not match the API schema.
 - configuration.entry should be one of these:
   object { <key>: non-empty string | [non-empty string] } | non-empty string | [non-empty string] | function
   -> The entry point(s) of the compilation.
   Details:
    * configuration.entry should not be empty.
      -> Multiple entry bundles are created. The key is the chunk name. The value can be a string or an array.
    * configuration.entry should be a string.
      -> An entry point without name. The string is resolved to a module which is loaded upon startup.
    * configuration.entry should be an array:
      [non-empty string]
    * configuration.entry should be an instance of function
      -> A Function returning an entry object, an entry string, an entry array or a promise to these things.
    at webpack (/home/XXX/XXX/chrome/wallext/node_modules/webpack/lib/webpack.js:19:9)
    at compile (/home/XXX/XXX/chrome/wallext/node_modules/webextension-toolbox/src/index.js:188:10)
    at Command.build (/home/XXX/XXX/chrome/wallext/node_modules/webextension-toolbox/bin/webextension-toolbox:43:5)
    at Command.listener (/home/XXX/XXX/chrome/wallext/node_modules/commander/index.js:315:8)
    at emitTwo (events.js:126:13)
    at Command.emit (events.js:214:7)
    at Command.parseArgs (/home/XXX/XXX/chrome/wallext/node_modules/commander/index.js:653:12)
    at Command.parse (/home/XXX/XXX/chrome/wallext/node_modules/commander/index.js:475:21)
    at Object.<anonymous> (/home/XXX/XXX/chrome/wallext/node_modules/webextension-toolbox/bin/webextension-toolbox:54:9)
    at Module._compile (module.js:643:30)
    at Object.Module._extensions..js (module.js:654:10)
    at Module.load (module.js:556:32)
    at tryModuleLoad (module.js:499:12)
    at Function.Module._load (module.js:491:3)
    at Function.Module.runMain (module.js:684:10)
    at startup (bootstrap_node.js:187:16)
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! [email protected] build: `webextension-toolbox build "chrome"`
npm ERR! Exit status 1
npm ERR! 
npm ERR! Failed at the [email protected] build script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     /home/XXX/.npm/_logs/2018-01-11T11_43_41_207Z-debug.log

Packed extensions can't be unzipped

After packing an extension and drag&dropping the ZIP into Chrome Extension UI these Errors are displayed:

Add pageCapture permission

Expected Behavior

Currently the extension will allow you specify permissions to add to the manifest. The list of permissions does not include pageCapture. here is a complete list of available permissions. Please look to add the missing ones. https://developer.chrome.com/extensions/permission_warnings

Current Behavior

Currently the permissions that are available do not include pageCapture.

Steps to Reproduce (for bugs)

1. run the the yeoman wizard
2. notice that the permissions step includes various permissions
3. permissions does not include pageCapture

Context

Minor issue as you can add the permissions afterwards. More for completeness.

Your Environment

Mac, but not relevant

Yarn can only be used when it is installed

When a user would like to use yarn, it needs to be installed, even when --skip-install option is used.
I think this check could be moved to the actual install phase, simply throwing a warning like "Yarn is not installed, skipping install. Please install yarn on your machine." is enough.
What do you think, @HaNdTriX ?

yo web-extension throws Unexpected Identifier error

After installing, yo and web-extension generator, when i run yo web-extension
the error is displayed.

`/usr/local/lib/node_modules/generator-web-extension/app/index.js:26
async prompting () {
^^^^^^^^^

SyntaxError: Unexpected identifier
at createScript (vm.js:56:10)
at Object.runInThisContext (vm.js:97:10)
at Module._compile (module.js:542:28)
at Object.Module._extensions..js (module.js:579:10)
at Module.load (module.js:487:32)
at tryModuleLoad (module.js:446:12)
at Function.Module._load (module.js:438:3)
at Module.require (module.js:497:17)
at require (internal/module.js:20:19)
at Object.get [as web-extension:app] (/usr/local/lib/node_modules/yo/node_modules/yeoman-environment/lib/store.js:38:27)
`
node --version
v6.11.2

browser not defined while running the example

npm run dev -- chrome
Displays browser not defined

Provide a test setup (mocha/jasmine) as part of generator

Can you provide a sample test case along with generator?

Make generated project fully compatible with Edge

Expected Behavior

Full Edge support out-of-the-box.

Current Behavior

After generating extension, we have to manually add author field to manifest.json and persistent property to the background page object.

Also, Edge doesn't support promises (yet), maybe use this polyfill version?

Steps to Reproduce (for bugs)

1. generate extension
2. run it
3. try to load it into Edge

Suggestion

1., Add persistent to manifest file by default (if we select to add background page), like this:

"background": {
    "scripts": [
        "scripts/background.js"
    ],
    "__chrome|edge|opera__persistent": false
},

Documentation
Browser compatibility (not supported in firefox)

2., Simply add author property to default manifest.json

Documentation (This key is mandatory in Microsoft Edge.)

3., Polyfill to Edge version
If i simply add the polyfill, browser will be undefined. I assume using this fixes the issue. Needs testing.

Documentation (Microsoft Edge extension APIs use callbacks, not promises.)

Your Environment

Tech	Version
generator-webextension	0.0.5
node	v10.4.0
OS	W10
browser
etc

[Help] JS Syntax

@HaNdTriX could you help me change my configs so that I can safely use ES7 / ES-next syntax?

Please provide details on usingreact with the extension?

What does out of box support for reacct mean?
Should I do npm install react to use react?

Move from Appveyor to Azure Devops

Improve yarn support

Maybe we can detect if a user uses yarn and then install all deps via yarn.

Todo

• Evaluate has-yarn
• Use yarn to install deps http://yeoman.io/authoring/dependencies.html

[question] its for many browsers? chrome, safari, opera and firefox?

Step by step guide?

Hello there.
First of all, thank you so much for this tool.

I am brand new to web extensions development and this is making everything smoother.
My question is: "shouldn't the YO generator put everything ready to go?"
After I run the YO command,
npm run dev chrome gives me errors:

myApp/node_modules/webextension-toolbox/src/compile.js:7 const { webpack, ...config } = getConfigFile() ^^^ SyntaxError: Unexpected token ... at Object.exports.runInThisContext (vm.js:73:16) at Module._compile (module.js:543:28) at Object.Module._extensions..js (module.js:580:10) at Module.load (module.js:488:32) at tryModuleLoad (module.js:447:12) at Function.Module._load (module.js:439:3) at Module.require (module.js:498:17) at require (internal/module.js:20:19) at Object.<anonymous> (/Users/beterraba/Documents/Workgit/webextensions/maxmilhas/node_modules/webextension-toolbox/index.js:1:79) at Module._compile (module.js:571:32)
As I understand, I am missing the webpack.config.js file. But shouldnt YO scaffold that?

Also, a step by step guide on how to quick start with
webextension-toolbox and webpack-webextension-plugin would be really awesome.

Tks in advance anyway and sorry if I am just missing something dumb! :)

browser undefined in background.js

Error

background.js:2 Uncaught ReferenceError: browser is not defined
    at background.js:2
(anonymous) @ background.js:2

background.js

browser.runtime.onInstalled.addListener((details) => {
  console.log('previousVersion', details.previousVersion)
})

browser.browserAction.setBadgeText({
  text: `'Allo`
})

console.log(`'Allo 'Allo! Event Page for Browser Action`)