{"_id":"589540223191370f0060dcd2","category":{"_id":"57e48a4000c8680e00fae6e7","version":"55a6e72f8cc73e0d00096638","__v":0,"project":"55a6e72e8cc73e0d00096635","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-09-23T01:49:52.242Z","from_sync":false,"order":3,"slug":"advanced-installation-options","title":"Advanced Installation Options"},"parentDoc":null,"user":"55a6caa022cfa321008e01d6","version":{"_id":"55a6e72f8cc73e0d00096638","project":"55a6e72e8cc73e0d00096635","hasReference":false,"__v":29,"hasDoc":true,"createdAt":"2015-07-15T23:05:19.125Z","releaseDate":"2015-07-15T23:05:19.125Z","categories":["55a6e7308cc73e0d00096639","55b7ed07aea7c8190058badb","5604567c0c78b00d0039b191","5605e6f23a93940d002b3e4a","5605f2bba4574a0d00811365","5605f309a4574a0d00811366","5608e3b98aedf50d0004cf8f","5608e4318aedf50d0004cf90","5608e6b5a7cc2f0d00d9754d","5608e6d331beb60d001b6560","5608f879a7cc2f0d00d97580","560b097887b71d0d000d3bd9","560b13cbafa0990d00979545","560b5cbec341310d00de2a01","560b5cd0c341310d00de2a02","566a35b81e08750d00a0c49b","566a3e8503b4b20d00d02a4a","567889d307bf6a0d0083edc8","569c8b7c15bb390d00db6f9d","56b254dc65ddf50d0076ba8f","57a8ebc4cdeea20e001d2a63","57e48a4000c8680e00fae6e7","5808216773557d0f00a1e428","58105ad54a8aa50f00aa4cba","58105bf298aea40f00afa3ba","58105f548a4aed0f00d67536","581061b898aea40f00afa3be","584b3de7e5f3a42300df6ef7","596839a75965d400155bb750"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"__v":1,"project":"55a6e72e8cc73e0d00096635","updates":["58ebcca9cbc3f70f009b9c28"],"next":{"pages":[],"description":""},"createdAt":"2017-02-04T02:44:50.297Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Optional Steps\",\n  \"body\": \"The steps on this page are required only if you plan to use Stencil CLI to customize source files from a published theme (_other_ than Cornerstone or Diamond Classic/Queen) downloaded from BigCommerce's Theme Marketplace. \\n\\nThese options apply to purchased themes, and to free themes <i>other</i> than Cornerstone, Diamond Classic, and Queen.\\n\\nIf you are downloading a refreshed copy of Stencil's default Cornerstone theme, the Diamond Classic theme, or the Queen theme, please instead use the simplified refresh instructions at <a href=\\\"/docs/downloading-and-refreshing-cornerstone\\\">Downloading a Refreshed Copy of Cornerstone</a>.\\n\\nCornerstone, Diamond Classic, Queen, and newer Marketplace themes (as identified below) use the <a href=\\\"https://webpack.github.io/docs/\\\">Webpack</a> JavaScript build system. You can customize Webpack's watched folders, or substitute your own build system. For details, please see <a href=\\\"/docs/webpack-and-build-options\\\">Webpack and Build-System Options</a>.\\n\\nTo keep _any_ custom or customized theme updated with the new features that BigCommerce adds to Cornerstone, please see our guidelines on [Theme Updates and Version Control](/docs/theme-updates-sync).\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"To use Stencil CLI to customize downloaded Marketplace themes (<i>other</i> than Cornerstone, Diamond Classic, and Queen), you must follow the workflow below:\\n\\n<ul>\\n\\t<li><a href=\\\"#bb.ssh\\\">Setting Up BitBucket SSH Keys</a>\\n\\t<li><a href=\\\"#download_theme\\\">Downloading a Theme for Customization</a>\\n\\t</li>\\n\\t<li><a href=\\\"#version_check\\\"> Checking the Theme's Version </a>\\n\\t</li>\\n\\t<li> <a href=\\\"#jspm_branch\\\"> jspm Extra Steps for Earlier Versions </a> \\n\\t</li>\\n\\t<ul> <!-- inner -->\\n\\t<li><a href=\\\"#Prereq.jspm\\\">Installing jspm</a>\\n  </li>\\n\\t<li><a href=\\\"#Register_jspm\\\">Registering the jspm Instance</a>\\n\\t</li>\\n  <li><a href=\\\"#jspm-git\\\">Installing jspm-git</a>\\n\\t</li>\\n  <li><a href=\\\"#BitBucket\\\">Adding BitBucket as a jspm Registry</a>\\n\\t</li>\\n\\t<li><a href=\\\"#install_jspm\\\">Installing Modules (jspm Themes)</a>\\n    </li> <p></p>\\n\\t</ul> <!-- inner -->\\n\\t<li><a href=\\\"#install_webpack\\\">Installing Modules (Webpack Themes)</a>\\n\\t</li>\\n\\t<li><a href=\\\"#next\\\">Next Steps</a>\\n\\t</li>\\n</ul> <br>\\n\\nBitBucket registry access is required for all themes except Cornerstone, Diamond Classic, and Queen. The indented steps (to enable jspm and jspm-git) are required only for earlier theme versions, as outlined below. <br>\\n\\n\\n<hr style=\\\"background-color:#4E75F8; border-width:0;color:#000000; height:2px; line-height:0; text-align:left; width:100%;\\\"/>\\n\\n<h2> <A NAME=\\\"bb.ssh\\\"></a> Setting Up BitBucket SSH Keys </h2>\\n\\nTo set up Stencil CLI for themes other than Cornerstone, Diamond Classic, and Queen, you must authorize communication among your local system, the <a href=\\\"https://bitbucket.org/product\\\" target=\\\"_blank\\\">BitBucket</a> registry, and GitHub.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Some Assembly Required\",\n  \"body\": \"Steps beyond this point require that you have active accounts on both BitBucket and GitHub.\"\n}\n[/block]\nTo authorize ongoing communication, you must set up a secure shell (SSH) key that is shared between BitBucket and GitHub. This is a multi-step process, which is beyond the scope of this documentation. However, we have tested the instructions at the following links, and found them to be reliable:\n\n* Setting up SSH for Git on BitBucket: \n[https://confluence.atlassian.com/bitbucket/set-up-ssh-for-git-728138079.html](https://confluence.atlassian.com/bitbucket/set-up-ssh-for-git-728138079.html)\n\n    (Follow the default instructions to create a key in your `~/.ssh/config`.)\n\n* Setting up SSH on GitHub (a series of linked steps):\n[https://help.github.com/articles/connecting-to-github-with-ssh/](https://help.github.com/articles/connecting-to-github-with-ssh/)\n<br>\n[block:html]\n{\n  \"html\": \"<hr style=\\\"background-color:#4E75F8; border-width:0;color:#000000; height:2px; line-height:0; text-align:left; width:100%;\\\"/>\\n\\n<h2> <A NAME=\\\"download_theme\\\"></a> Downloading a Theme for Customization </h2>\\n\\nUse these steps to download a theme available in the store control panel's <NOBR><span class=\\\"inline-code\\\">Storefront Design</span></nobr> area. <NOBR>(This page applies</nobr> to purchased themes, and to free themes <i>other</i> than Cornerstone, Diamond Classic, and Queen:) \\n\\n<ol>\\n\\t<li>If you have not yet added the theme to your store, start at <NOBR><span class=\\\"inline-code\\\">Storefront Design</span></nobr> &gt; <span class=\\\"inline-code\\\">Themes Marketplace</span>, and add the theme.\\n    <p></p></li>\\n\\n\\t<li>Go to <NOBR><span class=\\\"inline-code\\\">Storefront Design</span></nobr> &gt; <span class=\\\"inline-code\\\">My Themes</span>.\\n    <p></p></li> \\n  \\n\\t<li>Click the theme's thumbnail:\\n    \\n    <ul> <!-- inner -->\\n      <li>To download the store's currently active theme, click the image thumbnail at the top of the page, under the <NOBR><span class=\\\"inline-code\\\">Current Theme</span></nobr> heading.\\n      <p></p></li>\\n      <li>To download an inactive theme, scroll down below the lower <NOBR><span class=\\\"inline-code\\\">My Themes</span></nobr> subheading, and click the appropriate theme's thumbnail.\\n      <p></p></li>\\n\\t\\t</ul> <!-- inner -->\\n    \\n    Your selected theme will zoom up to a full-page description, and will display a <NOBR><span class=\\\"inline-code\\\">Theme Options</span></nobr> drop-down list at the <NOBR>upper right.</nobr>\\n    <p></p></li>\\n\\n\\t<li><a name=\\\"version_note\\\"></a>Note the version number displayed under the theme's title and credits. At <a href=\\\"#version_check\\\">Checking the Theme's Version</a> below, you will use this number to choose between two installation flows.\\n    <p></p></li>\\n\\n <li>From the <NOBR><span class=\\\"inline-code\\\">Theme Options</span></nobr> drop-down list, select the appropriate <span class=\\\"inline-code\\\">Download</span> option. (The options visible depend on your theme's current state:)\\n    <p></p>\\n    \\n    <ul> <!-- inner -->\\n      <li><NOBR><span class=\\\"inline-code\\\">Download current theme</span></nobr>: Download the theme version that is now active on the storefront. <NOBR>(This option</nobr> appears only if you selected the <NOBR><span class=\\\"inline-code\\\">Current Theme</span></nobr>.)\\n      <p></p></li>\\n      \\n      <li><NOBR><span class=\\\"inline-code\\\">Download your latest customizations</span></nobr>: Download the theme's most recently saved version. <NOBR>(This option</nobr> appears only for themes that have been customized for this store.)\\n      <p></p></li>\\n      \\n      <li><NOBR><span class=\\\"inline-code\\\">Download theme file</span></nobr>: Download the theme as it was originally uploaded to Theme Marketplace.\\n    <br><p></p>\\n\\t\\t<img src=\\\"https://files.readme.io/1f6939d-DownloadMake-CopyTheme-Optionsfull-menu.png\\\" alt=\\\"Theme Options &gt; Download options, superset for an active theme\\\">\\n  \\t<br><p></p> \\n    Selecting any of the above options will download a .zip file containing <!-- the <i>latest</i> version of --> the theme and version you specified.\\n      <p></p></li>\\n      \\n\\t\\t</ul> <!-- inner -->  \\n    \\n    <p></p></li>\\n\\n  <li>Unpack the zipped theme to a working directory.\\n    <p></p>\\n  (In the remainder of this documentation, substitute this working directory's name for the default <span class=\\\"inline-code\\\">&lt;stencil&gt;</span> path or the <span class=\\\"inline-code\\\">&lt;theme-name&gt;</span> placeholder.)</li>\\n</ol>\"\n}\n[/block]\n<span id=\"callouts\"></span>\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Theme Download Shortcuts\",\n  \"body\": \"Some versions of the BigCommerce control panel offer you shortcuts for steps 3–5 above, removing the need to click the theme card/thumbnail:\\n* For your store's currently active theme, look for a version number to the right of the thumbnail. Also,&#160;you&#160;can select the `Advanced` drop-down list to display options similar to those at step 5 above.\\n\\n* For inactive themes, look for a version number at the theme card's lower left. Also, you can select the \\\"`...`\\\" menu at the theme card's lower right to display options similar to those at step 5 above.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Theme Access, Copyright/Ownership, and Distribution\",\n  \"body\": \"* Except for free themes (Cornerstone and Fortune), Marketplace themes must be purchased in order to be downloadable.\\n\\n* You are entitled to customize a free or purchased theme for a store that you support. However, the theme's original creator retains rights to that theme's design. So, except for Cornerstone-based themes, you may not upload a derived theme to a public theme marketplace (whether BigCommerce's or third-party), nor sell it privately.\\n\\n* Distribution of Cornerstone-based themes is subject to BigCommerce's [Cornerstone license](/docs/cornerstone-license), including the mandatory incorporation of BigCommerce's copyright statement.\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<p></p>\\n<hr style=\\\"background-color:#4E75F8; border-width:0;color:#000000; height:2px; line-height:0; text-align:left; width:100%;\\\"/>\\n\\n<h2> <A NAME=\\\"version_check\\\"></a> Checking the Theme's Version </h2>\\n\\nRefer to the theme's version number that you you noted above at <a href=\\\"#version_note\\\">Downloading a Theme for Customization</a>:\\n\\n<ul>\\n\\t<li>If the version number is <span class=\\\"inline-code\\\">1.10.0</span> or higher, the theme uses Webpack as its JavaScript build system. <br> \\n\\tSkip ahead to the simplified installation instructions below at <a href=\\\"#install_webpack\\\">Installing Modules (Webpack Themes)</a>.\\n    <p></p>\\n  </li>\\n\\t<li>If the version number is lower than <span class=\\\"inline-code\\\">1.10.0</span>, the theme uses jspm as its JavaScript build system. <br>\\n\\tFollow the <a href=\\\"#jspm_branch\\\">jspm Extra Steps for Earlier Versions</a> directly below.\\n\\t</li>\\n</ul>\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Consider Refreshing the Theme Version\",\n  \"body\": \"For version numbers below <span class=\\\"inline-code\\\">1.10.0</span>, consider using the options within control panel > `My Themes` to download a newer version of the same theme. This will allow you to jump ahead to the streamlined instructions below at <a href=\\\"#install_webpack\\\">Installing&#160;Modules (Webpack Themes)</a>.\\n\\nAs a reminder: These version numbers do not apply to the Cornerstone theme. All currently supported Cornerstone versions use Webpack, and can be refreshed using the even simpler refresh instructions at <a href=\\\"/docs/downloading-and-refreshing-cornerstone\\\">Downloading a Refreshed Copy of Cornerstone</a>.\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<hr style=\\\"background-color:#4E75F8; border-width:0;color:#000000; height:2px; line-height:0; text-align:left; width:100%;\\\"/>\\n\\n<h2> <A NAME=\\\"jspm_branch\\\"></a> jspm Extra Steps for Earlier Versions </h2>\\n\\nUse the following steps for Marketplace themes (_other_ than Cornerstone) whose version number is lower than <span class=\\\"inline-code\\\">1.10.0</span>.\\n\\n\\n<br>\\n<hr style=\\\"background-color:#4E75F8; border-width:0;color:#000000; height:2px; line-height:0; text-align:left; width:100%;\\\"/>\\n\\n<h3> <A NAME=\\\"Prereq.jspm\\\"></a>Installing jspm </h3>\\n\\nYou must install <a href=\\\"http://jspm.io/\\\">jspm</a> to manage your pre-<span class=\\\"inline-code\\\">1.10.0</span> theme's JavaScript dependencies. We have tested Stencil on jspm version 0.16.30 for Mac OS and Linux, and on version 0.16.31 for Windows. Use the following <a href=\\\"/docs/prerequisites#Prereq.npm\\\">npm</a>  command to install a tested version of jspm with global scope &ndash; for Mac OS or Linux:\\n<p></p>\\n\\n  <pre>\\n  npm install -g jspm:::at:::0.16.30  </pre><p></p>\\n\\nOr, for Windows:<p></p>\\n\\n  <pre>\\n  npm install -g jspm@0.16.31  </pre>\\n  \\nYou can use the same command to upgrade an earlier jspm installation to a Stencil-supported version.\\n\\n<br>\\n<hr style=\\\"background-color:#4E75F8; border-width:0;color:#000000; height:2px; line-height:0; text-align:left; width:100%;\\\"/>\\n\\n<h3> <A NAME=\\\"Register_jspm\\\"></a> Registering the jspm Instance </h3>\\n\\nNext, register your jspm instance with GitHub.<br>\\n\\n<ol>\\n  <li>Navigate to your GitHub Personal Access Tokens page <NOBR>(<a href=\\\"https://github.com/settings/tokens\\\">https://github.com/settings/tokens</a>).</nobr>\\n</li> <p></p>\\n\\n<li>\\n  Generate a new personal access token with the name <span class=\\\"inline-code\\\">Stencil</span> and scope <span class=\\\"inline-code\\\">repo</span>. (GitHub provides specific instructions here: <NOBR><a href=\\\"https://help.github.com/articles/generating-an-ssh-key/\\\">https://help.github.com/articles/generating-an-ssh-key/</a>.)</nobr>\\n</li> <p></p>\\n\\n<li>\\n  Verify that your new token includes the following scopes: \\n  \\n  <ul>\\n    <li><span class=\\\"inline-code\\\">repo:status</span>\\n    </li>\\n    <li><span class=\\\"inline-code\\\">repo_deployment</span>\\n    </li>\\n    <li><span class=\\\"inline-code\\\">public_repo</span>\\n    </li> \\n  </ul> \\n  \\n</li> <p></p>\\n\\n<li>Once you have generated your token, run the following command to associate your jspm module with your GitHub account:</li> <p></p>\\n\\n<pre>\\njspm registry config github</pre>\\n<p></p>\\n\\n<li>You will be prompted to enter your authentication token (<span class=\\\"inline-code\\\">\\\"Set up GitHub credentials?\\\"</span>). Copy and paste the personal access token you created just above.</li>\\n</ol>\\n\\n\\n<hr style=\\\"background-color:#4E75F8; border-width:0;color:#000000; height:2px; line-height:0; text-align:left; width:100%;\\\"/>\\n\\n<h3> <A NAME=\\\"jspm-git\\\"></a> Installing jspm-git </h3>\\n\\nFor the next step, you will need the <a href=\\\"https://www.npmjs.com/package/jspm-git\\\">jspm-git</a> registry plug-in.<p></p>\\n\\nTo install it with global scope, enter the following on a command line:<p></p>\\n\\n<pre>\\nnpm install -g jspm-git</pre>\\n\\nIf you already have an earlier version of jspm-git installed, you might need to update it to handle Git projects with two-digit version numbers (such as <span class=\\\"inline-code\\\">1.10.0</span>). If so, use this command:<p></p>\\n\\n<pre>npm upgrade jspm-git@latest\\n</pre>\\n\\n\\n<hr style=\\\"background-color:#4E75F8; border-width:0;color:#000000; height:2px; line-height:0; text-align:left; width:100%;\\\"/>\\n\\n<h3> <A NAME=\\\"BitBucket\\\"></a> Adding BitBucket as a jspm Registry </h3>\\n\\nWorking with downloaded Marketplace themes requires that you next add BitBucket as a registry for jspm. To&#160;proceed, set up a <a href=\\\"https://bitbucket.org/product\\\" target=\\\"_blank\\\">BitBucket</a> account, if you do not already have one.<p></p> \\n\\nNext, enter the following on a command line:<p></p>\\n\\n<pre>\\njspm registry create bitbucket jspm-git</pre><p></p>\\n\\nYou will be prompted for a base URL for your git server. Enter the following:<p></p>\\n\\n<pre>\\nssh://git@bitbucket.org</pre>\\n\\n\\n<hr style=\\\"background-color:#4E75F8; border-width:0;color:#000000; height:2px; line-height:0; text-align:left; width:100%;\\\"/>\\n\\n<h3> <A NAME=\\\"install_jspm\\\"></a> Installing Modules (jspm Themes) </h3>\\n\\nNext, install the npm and jspm modules required to access Stencil JavaScript events:<p></p>\\n\\n<ol>\\n\\t<li>Navigate to your theme directory. This example assumes that this target directory has the default name <span class=\\\"inline-code\\\">stencil</span>:</li><p></p>\\n\\n<pre>\\ncd stencil </pre>\\n\\n\\t<li>Within that directory, install (or reinstall) the <span class=\\\"inline-code\\\">stencil-utils</span> module to ensure that all your dependencies are up to date:</li><p></p>\\n\\n<pre>\\nnpm install </pre>\\n\\n\\n\\t<li>Then execute the following command to complete installation:</li><p></p>\\n\\n<pre>\\njspm install</pre>\\n</ol>\\n\\nThis concludes jspm setup instructions for Marketplace themes with version numbers lower than <span class=\\\"inline-code\\\">1.10.0</span>. Skip&#160;ahead to <a href=\\\"#next\\\">Next Steps</a> below.\\n\\n\\n<hr style=\\\"background-color:#4E75F8; border-width:0;color:#000000; height:2px; line-height:0; text-align:left; width:100%;\\\"/>\\n\\n<h2> <A NAME=\\\"install_webpack\\\"></a> Installing Modules (Webpack Themes) </h2>\\n\\nFor Marketplace themes whose version number is <span class=\\\"inline-code\\\">1.10.0</span> or higher, simply use npm to install the modules required to access Stencil JavaScript events:<p></p>\\n\\n<ol>\\n\\t<li>Navigate to your theme directory. This example assumes that this target directory has the default name <span class=\\\"inline-code\\\">stencil</span>:</li><p></p>\\n\\n<pre>\\ncd stencil </pre>\\n\\n\\t<li>Within that directory, install (or reinstall) the <span class=\\\"inline-code\\\">stencil-utils</span> module to ensure that all your dependencies are up to date:</li><p></p>\\n\\n<pre>\\nnpm install </pre>\\n</ol>\\n\\n\\n<hr style=\\\"background-color:#4E75F8; border-width:0;color:#000000; height:2px; line-height:0; text-align:left; width:100%;\\\"/>\\n\\n<h2> <A NAME=\\\"next\\\"></a> Next Steps </h2>  \\n\\nTo authorize, initialize, and launch your theme, follow the steps listed in the <a href=\\\"/docs/launching-stencil\\\">Launching Stencil</a> subsection.\\n<p></p>\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"When you issue the `stencil init` command to [authorize and initialize Stencil](/docs/initializing-stencil), you might receive error messages about resolving BitBucket as an SSH host. These errors occur when you have not recently logged into BitBucket. \\n\\nWhen prompted, enter the BitBucket password you used in <a href=\\\"#bb.ssh\\\">Setting Up BitBucket SSH Keys</a> above. This will clear the errors and allow you to proceed.\",\n  \"title\": \"BitBucket Reauthentication\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"Later, when you are ready to upload your customized theme to a store, you should follow the zipping and uploading instructions in <a href=\\\"https://stencil.bigcommerce.com/docs/bundling-submitting\\\">Bundling and Submitting a Theme</a> and <a href=\\\"/docs/uploading-a-custom-theme\\\">Troubleshooting Theme Uploads</a>.\"\n}\n[/block]","excerpt":"(Applies to themes _other than_ Cornerstone, Diamond Classic, and Queen)","slug":"downloading-and-customizing-marketplace-themes","type":"basic","title":"Downloading/Customizing Marketplace Themes"}

Downloading/Customizing Marketplace Themes

(Applies to themes _other than_ Cornerstone, Diamond Classic, and Queen)

[block:callout] { "type": "info", "title": "Optional Steps", "body": "The steps on this page are required only if you plan to use Stencil CLI to customize source files from a published theme (_other_ than Cornerstone or Diamond Classic/Queen) downloaded from BigCommerce's Theme Marketplace. \n\nThese options apply to purchased themes, and to free themes <i>other</i> than Cornerstone, Diamond Classic, and Queen.\n\nIf you are downloading a refreshed copy of Stencil's default Cornerstone theme, the Diamond Classic theme, or the Queen theme, please instead use the simplified refresh instructions at <a href=\"/docs/downloading-and-refreshing-cornerstone\">Downloading a Refreshed Copy of Cornerstone</a>.\n\nCornerstone, Diamond Classic, Queen, and newer Marketplace themes (as identified below) use the <a href=\"https://webpack.github.io/docs/\">Webpack</a> JavaScript build system. You can customize Webpack's watched folders, or substitute your own build system. For details, please see <a href=\"/docs/webpack-and-build-options\">Webpack and Build-System Options</a>.\n\nTo keep _any_ custom or customized theme updated with the new features that BigCommerce adds to Cornerstone, please see our guidelines on [Theme Updates and Version Control](/docs/theme-updates-sync)." } [/block] [block:html] { "html": "To use Stencil CLI to customize downloaded Marketplace themes (<i>other</i> than Cornerstone, Diamond Classic, and Queen), you must follow the workflow below:\n\n<ul>\n\t<li><a href=\"#bb.ssh\">Setting Up BitBucket SSH Keys</a>\n\t<li><a href=\"#download_theme\">Downloading a Theme for Customization</a>\n\t</li>\n\t<li><a href=\"#version_check\"> Checking the Theme's Version </a>\n\t</li>\n\t<li> <a href=\"#jspm_branch\"> jspm Extra Steps for Earlier Versions </a> \n\t</li>\n\t<ul> <!-- inner -->\n\t<li><a href=\"#Prereq.jspm\">Installing jspm</a>\n </li>\n\t<li><a href=\"#Register_jspm\">Registering the jspm Instance</a>\n\t</li>\n <li><a href=\"#jspm-git\">Installing jspm-git</a>\n\t</li>\n <li><a href=\"#BitBucket\">Adding BitBucket as a jspm Registry</a>\n\t</li>\n\t<li><a href=\"#install_jspm\">Installing Modules (jspm Themes)</a>\n </li> <p></p>\n\t</ul> <!-- inner -->\n\t<li><a href=\"#install_webpack\">Installing Modules (Webpack Themes)</a>\n\t</li>\n\t<li><a href=\"#next\">Next Steps</a>\n\t</li>\n</ul> <br>\n\nBitBucket registry access is required for all themes except Cornerstone, Diamond Classic, and Queen. The indented steps (to enable jspm and jspm-git) are required only for earlier theme versions, as outlined below. <br>\n\n\n<hr style=\"background-color:#4E75F8; border-width:0;color:#000000; height:2px; line-height:0; text-align:left; width:100%;\"/>\n\n<h2> <A NAME=\"bb.ssh\"></a> Setting Up BitBucket SSH Keys </h2>\n\nTo set up Stencil CLI for themes other than Cornerstone, Diamond Classic, and Queen, you must authorize communication among your local system, the <a href=\"https://bitbucket.org/product\" target=\"_blank\">BitBucket</a> registry, and GitHub." } [/block] [block:callout] { "type": "warning", "title": "Some Assembly Required", "body": "Steps beyond this point require that you have active accounts on both BitBucket and GitHub." } [/block] To authorize ongoing communication, you must set up a secure shell (SSH) key that is shared between BitBucket and GitHub. This is a multi-step process, which is beyond the scope of this documentation. However, we have tested the instructions at the following links, and found them to be reliable: * Setting up SSH for Git on BitBucket: [https://confluence.atlassian.com/bitbucket/set-up-ssh-for-git-728138079.html](https://confluence.atlassian.com/bitbucket/set-up-ssh-for-git-728138079.html) (Follow the default instructions to create a key in your `~/.ssh/config`.) * Setting up SSH on GitHub (a series of linked steps): [https://help.github.com/articles/connecting-to-github-with-ssh/](https://help.github.com/articles/connecting-to-github-with-ssh/) <br> [block:html] { "html": "<hr style=\"background-color:#4E75F8; border-width:0;color:#000000; height:2px; line-height:0; text-align:left; width:100%;\"/>\n\n<h2> <A NAME=\"download_theme\"></a> Downloading a Theme for Customization </h2>\n\nUse these steps to download a theme available in the store control panel's <NOBR><span class=\"inline-code\">Storefront Design</span></nobr> area. <NOBR>(This page applies</nobr> to purchased themes, and to free themes <i>other</i> than Cornerstone, Diamond Classic, and Queen:) \n\n<ol>\n\t<li>If you have not yet added the theme to your store, start at <NOBR><span class=\"inline-code\">Storefront Design</span></nobr> &gt; <span class=\"inline-code\">Themes Marketplace</span>, and add the theme.\n <p></p></li>\n\n\t<li>Go to <NOBR><span class=\"inline-code\">Storefront Design</span></nobr> &gt; <span class=\"inline-code\">My Themes</span>.\n <p></p></li> \n \n\t<li>Click the theme's thumbnail:\n \n <ul> <!-- inner -->\n <li>To download the store's currently active theme, click the image thumbnail at the top of the page, under the <NOBR><span class=\"inline-code\">Current Theme</span></nobr> heading.\n <p></p></li>\n <li>To download an inactive theme, scroll down below the lower <NOBR><span class=\"inline-code\">My Themes</span></nobr> subheading, and click the appropriate theme's thumbnail.\n <p></p></li>\n\t\t</ul> <!-- inner -->\n \n Your selected theme will zoom up to a full-page description, and will display a <NOBR><span class=\"inline-code\">Theme Options</span></nobr> drop-down list at the <NOBR>upper right.</nobr>\n <p></p></li>\n\n\t<li><a name=\"version_note\"></a>Note the version number displayed under the theme's title and credits. At <a href=\"#version_check\">Checking the Theme's Version</a> below, you will use this number to choose between two installation flows.\n <p></p></li>\n\n <li>From the <NOBR><span class=\"inline-code\">Theme Options</span></nobr> drop-down list, select the appropriate <span class=\"inline-code\">Download</span> option. (The options visible depend on your theme's current state:)\n <p></p>\n \n <ul> <!-- inner -->\n <li><NOBR><span class=\"inline-code\">Download current theme</span></nobr>: Download the theme version that is now active on the storefront. <NOBR>(This option</nobr> appears only if you selected the <NOBR><span class=\"inline-code\">Current Theme</span></nobr>.)\n <p></p></li>\n \n <li><NOBR><span class=\"inline-code\">Download your latest customizations</span></nobr>: Download the theme's most recently saved version. <NOBR>(This option</nobr> appears only for themes that have been customized for this store.)\n <p></p></li>\n \n <li><NOBR><span class=\"inline-code\">Download theme file</span></nobr>: Download the theme as it was originally uploaded to Theme Marketplace.\n <br><p></p>\n\t\t<img src=\"https://files.readme.io/1f6939d-DownloadMake-CopyTheme-Optionsfull-menu.png\" alt=\"Theme Options &gt; Download options, superset for an active theme\">\n \t<br><p></p> \n Selecting any of the above options will download a .zip file containing <!-- the <i>latest</i> version of --> the theme and version you specified.\n <p></p></li>\n \n\t\t</ul> <!-- inner --> \n \n <p></p></li>\n\n <li>Unpack the zipped theme to a working directory.\n <p></p>\n (In the remainder of this documentation, substitute this working directory's name for the default <span class=\"inline-code\">&lt;stencil&gt;</span> path or the <span class=\"inline-code\">&lt;theme-name&gt;</span> placeholder.)</li>\n</ol>" } [/block] <span id="callouts"></span> [block:callout] { "type": "success", "title": "Theme Download Shortcuts", "body": "Some versions of the BigCommerce control panel offer you shortcuts for steps 3–5 above, removing the need to click the theme card/thumbnail:\n* For your store's currently active theme, look for a version number to the right of the thumbnail. Also,&#160;you&#160;can select the `Advanced` drop-down list to display options similar to those at step 5 above.\n\n* For inactive themes, look for a version number at the theme card's lower left. Also, you can select the \"`...`\" menu at the theme card's lower right to display options similar to those at step 5 above." } [/block] [block:callout] { "type": "warning", "title": "Theme Access, Copyright/Ownership, and Distribution", "body": "* Except for free themes (Cornerstone and Fortune), Marketplace themes must be purchased in order to be downloadable.\n\n* You are entitled to customize a free or purchased theme for a store that you support. However, the theme's original creator retains rights to that theme's design. So, except for Cornerstone-based themes, you may not upload a derived theme to a public theme marketplace (whether BigCommerce's or third-party), nor sell it privately.\n\n* Distribution of Cornerstone-based themes is subject to BigCommerce's [Cornerstone license](/docs/cornerstone-license), including the mandatory incorporation of BigCommerce's copyright statement." } [/block] [block:html] { "html": "<p></p>\n<hr style=\"background-color:#4E75F8; border-width:0;color:#000000; height:2px; line-height:0; text-align:left; width:100%;\"/>\n\n<h2> <A NAME=\"version_check\"></a> Checking the Theme's Version </h2>\n\nRefer to the theme's version number that you you noted above at <a href=\"#version_note\">Downloading a Theme for Customization</a>:\n\n<ul>\n\t<li>If the version number is <span class=\"inline-code\">1.10.0</span> or higher, the theme uses Webpack as its JavaScript build system. <br> \n\tSkip ahead to the simplified installation instructions below at <a href=\"#install_webpack\">Installing Modules (Webpack Themes)</a>.\n <p></p>\n </li>\n\t<li>If the version number is lower than <span class=\"inline-code\">1.10.0</span>, the theme uses jspm as its JavaScript build system. <br>\n\tFollow the <a href=\"#jspm_branch\">jspm Extra Steps for Earlier Versions</a> directly below.\n\t</li>\n</ul>" } [/block] [block:callout] { "type": "success", "title": "Consider Refreshing the Theme Version", "body": "For version numbers below <span class=\"inline-code\">1.10.0</span>, consider using the options within control panel > `My Themes` to download a newer version of the same theme. This will allow you to jump ahead to the streamlined instructions below at <a href=\"#install_webpack\">Installing&#160;Modules (Webpack Themes)</a>.\n\nAs a reminder: These version numbers do not apply to the Cornerstone theme. All currently supported Cornerstone versions use Webpack, and can be refreshed using the even simpler refresh instructions at <a href=\"/docs/downloading-and-refreshing-cornerstone\">Downloading a Refreshed Copy of Cornerstone</a>." } [/block] [block:html] { "html": "<hr style=\"background-color:#4E75F8; border-width:0;color:#000000; height:2px; line-height:0; text-align:left; width:100%;\"/>\n\n<h2> <A NAME=\"jspm_branch\"></a> jspm Extra Steps for Earlier Versions </h2>\n\nUse the following steps for Marketplace themes (_other_ than Cornerstone) whose version number is lower than <span class=\"inline-code\">1.10.0</span>.\n\n\n<br>\n<hr style=\"background-color:#4E75F8; border-width:0;color:#000000; height:2px; line-height:0; text-align:left; width:100%;\"/>\n\n<h3> <A NAME=\"Prereq.jspm\"></a>Installing jspm </h3>\n\nYou must install <a href=\"http://jspm.io/\">jspm</a> to manage your pre-<span class=\"inline-code\">1.10.0</span> theme's JavaScript dependencies. We have tested Stencil on jspm version 0.16.30 for Mac OS and Linux, and on version 0.16.31 for Windows. Use the following <a href=\"/docs/prerequisites#Prereq.npm\">npm</a> command to install a tested version of jspm with global scope &ndash; for Mac OS or Linux:\n<p></p>\n\n <pre>\n npm install -g jspm@0.16.30 </pre><p></p>\n\nOr, for Windows:<p></p>\n\n <pre>\n npm install -g jspm@0.16.31 </pre>\n \nYou can use the same command to upgrade an earlier jspm installation to a Stencil-supported version.\n\n<br>\n<hr style=\"background-color:#4E75F8; border-width:0;color:#000000; height:2px; line-height:0; text-align:left; width:100%;\"/>\n\n<h3> <A NAME=\"Register_jspm\"></a> Registering the jspm Instance </h3>\n\nNext, register your jspm instance with GitHub.<br>\n\n<ol>\n <li>Navigate to your GitHub Personal Access Tokens page <NOBR>(<a href=\"https://github.com/settings/tokens\">https://github.com/settings/tokens</a>).</nobr>\n</li> <p></p>\n\n<li>\n Generate a new personal access token with the name <span class=\"inline-code\">Stencil</span> and scope <span class=\"inline-code\">repo</span>. (GitHub provides specific instructions here: <NOBR><a href=\"https://help.github.com/articles/generating-an-ssh-key/\">https://help.github.com/articles/generating-an-ssh-key/</a>.)</nobr>\n</li> <p></p>\n\n<li>\n Verify that your new token includes the following scopes: \n \n <ul>\n <li><span class=\"inline-code\">repo:status</span>\n </li>\n <li><span class=\"inline-code\">repo_deployment</span>\n </li>\n <li><span class=\"inline-code\">public_repo</span>\n </li> \n </ul> \n \n</li> <p></p>\n\n<li>Once you have generated your token, run the following command to associate your jspm module with your GitHub account:</li> <p></p>\n\n<pre>\njspm registry config github</pre>\n<p></p>\n\n<li>You will be prompted to enter your authentication token (<span class=\"inline-code\">\"Set up GitHub credentials?\"</span>). Copy and paste the personal access token you created just above.</li>\n</ol>\n\n\n<hr style=\"background-color:#4E75F8; border-width:0;color:#000000; height:2px; line-height:0; text-align:left; width:100%;\"/>\n\n<h3> <A NAME=\"jspm-git\"></a> Installing jspm-git </h3>\n\nFor the next step, you will need the <a href=\"https://www.npmjs.com/package/jspm-git\">jspm-git</a> registry plug-in.<p></p>\n\nTo install it with global scope, enter the following on a command line:<p></p>\n\n<pre>\nnpm install -g jspm-git</pre>\n\nIf you already have an earlier version of jspm-git installed, you might need to update it to handle Git projects with two-digit version numbers (such as <span class=\"inline-code\">1.10.0</span>). If so, use this command:<p></p>\n\n<pre>npm upgrade jspm-git@latest\n</pre>\n\n\n<hr style=\"background-color:#4E75F8; border-width:0;color:#000000; height:2px; line-height:0; text-align:left; width:100%;\"/>\n\n<h3> <A NAME=\"BitBucket\"></a> Adding BitBucket as a jspm Registry </h3>\n\nWorking with downloaded Marketplace themes requires that you next add BitBucket as a registry for jspm. To&#160;proceed, set up a <a href=\"https://bitbucket.org/product\" target=\"_blank\">BitBucket</a> account, if you do not already have one.<p></p> \n\nNext, enter the following on a command line:<p></p>\n\n<pre>\njspm registry create bitbucket jspm-git</pre><p></p>\n\nYou will be prompted for a base URL for your git server. Enter the following:<p></p>\n\n<pre>\nssh://git@bitbucket.org</pre>\n\n\n<hr style=\"background-color:#4E75F8; border-width:0;color:#000000; height:2px; line-height:0; text-align:left; width:100%;\"/>\n\n<h3> <A NAME=\"install_jspm\"></a> Installing Modules (jspm Themes) </h3>\n\nNext, install the npm and jspm modules required to access Stencil JavaScript events:<p></p>\n\n<ol>\n\t<li>Navigate to your theme directory. This example assumes that this target directory has the default name <span class=\"inline-code\">stencil</span>:</li><p></p>\n\n<pre>\ncd stencil </pre>\n\n\t<li>Within that directory, install (or reinstall) the <span class=\"inline-code\">stencil-utils</span> module to ensure that all your dependencies are up to date:</li><p></p>\n\n<pre>\nnpm install </pre>\n\n\n\t<li>Then execute the following command to complete installation:</li><p></p>\n\n<pre>\njspm install</pre>\n</ol>\n\nThis concludes jspm setup instructions for Marketplace themes with version numbers lower than <span class=\"inline-code\">1.10.0</span>. Skip&#160;ahead to <a href=\"#next\">Next Steps</a> below.\n\n\n<hr style=\"background-color:#4E75F8; border-width:0;color:#000000; height:2px; line-height:0; text-align:left; width:100%;\"/>\n\n<h2> <A NAME=\"install_webpack\"></a> Installing Modules (Webpack Themes) </h2>\n\nFor Marketplace themes whose version number is <span class=\"inline-code\">1.10.0</span> or higher, simply use npm to install the modules required to access Stencil JavaScript events:<p></p>\n\n<ol>\n\t<li>Navigate to your theme directory. This example assumes that this target directory has the default name <span class=\"inline-code\">stencil</span>:</li><p></p>\n\n<pre>\ncd stencil </pre>\n\n\t<li>Within that directory, install (or reinstall) the <span class=\"inline-code\">stencil-utils</span> module to ensure that all your dependencies are up to date:</li><p></p>\n\n<pre>\nnpm install </pre>\n</ol>\n\n\n<hr style=\"background-color:#4E75F8; border-width:0;color:#000000; height:2px; line-height:0; text-align:left; width:100%;\"/>\n\n<h2> <A NAME=\"next\"></a> Next Steps </h2> \n\nTo authorize, initialize, and launch your theme, follow the steps listed in the <a href=\"/docs/launching-stencil\">Launching Stencil</a> subsection.\n<p></p>" } [/block] [block:callout] { "type": "warning", "body": "When you issue the `stencil init` command to [authorize and initialize Stencil](/docs/initializing-stencil), you might receive error messages about resolving BitBucket as an SSH host. These errors occur when you have not recently logged into BitBucket. \n\nWhen prompted, enter the BitBucket password you used in <a href=\"#bb.ssh\">Setting Up BitBucket SSH Keys</a> above. This will clear the errors and allow you to proceed.", "title": "BitBucket Reauthentication" } [/block] [block:html] { "html": "Later, when you are ready to upload your customized theme to a store, you should follow the zipping and uploading instructions in <a href=\"https://stencil.bigcommerce.com/docs/bundling-submitting\">Bundling and Submitting a Theme</a> and <a href=\"/docs/uploading-a-custom-theme\">Troubleshooting Theme Uploads</a>." } [/block]