chrome/common/extensions/docs/templates/articles/shared_modules.html

   1 <h1>Shared Modules</h1><p>
   2 <em>Shared Modules</em> are permissionless collections of resources
   3 that can be shared between other extensions and apps.  Common
   4 uses of Shared Modules are:
   5 </p>
   6
   7 <ul>
   8   <li>
   9     As an API.  You can distribute a Shared Module that can
  10     provide HTML, JS, and other source to provide an API which
  11     can be updated independently of the extensions that depend
  12     on it.  This can be useful for runtimes and game engines,
  13     where apps are often smaller payloads of data that run on
  14     the Shared Module's code.
  15   </li>
  16   <li>
  17     As a download optimization.  The Shared Module contains common
  18     resources used by many extensions.  It's downloaded once,
  19     the first time a dependent extension is installed.
  20   </li>
  21 </ul>
  22
  23
  24 <h2 id="manifest"> Manifest </h2>
  25 <p>
  26 Shared Modules are used through two
  27 <a href="manifest">manifest</a> fields: export and import.
  28 </p>
  29
  30 <p>
  31 The <em>export</em> field indicates an extension is
  32 a Shared Module that exports its resources:
  33 </p>
  34
  35 <pre data-filename="manifest.json">
  36 {
  37   "version": "1.0",
  38   "name": "My Shared Module",
  39   <b>"export": {
  40     // Optional list of extension IDs explicitly allowed to
  41     // import this Shared Module's resources.  If no whitelist
  42     // is given, all extensions are allowed to import it.
  43     "whitelist": [
  44       "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  45       "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
  46     ]
  47   }</b>
  48   // Note: no permissions are allowed in Shared Modules
  49 }
  50 </pre>
  51
  52 <p>
  53 The <em>import</em> field is used by extensions and apps
  54 to declare that they depend on the resources from particular
  55 Shared Modules:
  56 </p>
  57
  58 <pre data-filename="manifest.json">
  59 {
  60   "version": "1.0",
  61   "name": "My Importing Extension",
  62   ...
  63   <b>"import": [
  64     {"id": "cccccccccccccccccccccccccccccccc"},
  65     {"id": "dddddddddddddddddddddddddddddddd"
  66      "minimum_version": "0.5" // optional
  67     },
  68   ]</b>
  69 }
  70 </pre>
  71
  72 <h2 id="accessing_resources"> Accessing Resources </h2>
  73
  74 <p>
  75 Shared Module resources are accessed by a reserved path
  76 <em>_modules/&lt;shared_module_id&gt;</em> in the root of
  77 your importing extension. For example, to include the script
  78 'foo.js' from a Shared Module with ID
  79 "cccccccccccccccccccccccccccccccc", use this path from the
  80 root of your extension:
  81 </p>
  82
  83 <code>
  84 &lt;script src="_modules/cccccccccccccccccccccccccccccccc/foo.js"&gt;
  85 </code>
  86
  87 <p>
  88 If the importing extension has ID "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  89 then the full URL to resources in the Shared Module is:
  90 </p>
  91
  92 <code>
  93 chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/_modules/cccccccccccccccccccccccccccccccc/
  94 </code>
  95
  96 <p>
  97 Note that since resources from Shared Modules are overlaid into
  98 the origin of the importing extension, all privileges granted to
  99 the importing extension are available to code in Shared Modules.
 100 Also, the Shared Module is able to access resources in the importing
 101 extension by using absolute paths.
 102 </p>
 103
 104 <h2 id="install_uninstall"> Install / Uninstall </h2>
 105
 106 <p>
 107 A Shared Module is automatically installed from the Chrome Web Store
 108 when needed by a dependent extension, and automatically uninstalled
 109 when the last extension which references it is uninstalled.  In order
 110 to upload an extension which uses a Shared Module, the Shared Module
 111 must be published in the Chrome Web Store and the extension must
 112 not be restricted from using the Shared Module by its whitelist.
 113 </p>
 114
 115 <p>
 116 During development, you will need to manually install any Shared Modules
 117 your extension uses.  Automatic installs do not happen for extensions
 118 that are side-loaded or loaded as unpacked extensions.  For locally
 119 installed, unpacked Shared Modules, you must use the
 120 <a href="manifest/key">key</a> field to ensure the Shared
 121 Modules use the correct IDs.
 122 </p>