{"id":13498865,"url":"https://github.com/jupyter-widgets/widget-cookiecutter","last_synced_at":"2025-04-04T17:07:17.784Z","repository":{"id":8385934,"uuid":"58143143","full_name":"jupyter-widgets/widget-cookiecutter","owner":"jupyter-widgets","description":"A cookiecutter template for creating a custom Jupyter widget project.","archived":false,"fork":false,"pushed_at":"2024-01-22T17:48:47.000Z","size":96,"stargazers_count":258,"open_issues_count":13,"forks_count":72,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-03-28T16:05:42.411Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jupyter-widgets.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-05-05T15:58:21.000Z","updated_at":"2024-11-06T09:05:33.000Z","dependencies_parsed_at":"2024-10-31T16:43:16.715Z","dependency_job_id":null,"html_url":"https://github.com/jupyter-widgets/widget-cookiecutter","commit_stats":{"total_commits":86,"total_committers":30,"mean_commits":"2.8666666666666667","dds":0.7558139534883721,"last_synced_commit":"134946a47f58aca8fb0a6b89197c315d1a6ec797"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jupyter-widgets%2Fwidget-cookiecutter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jupyter-widgets%2Fwidget-cookiecutter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jupyter-widgets%2Fwidget-cookiecutter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jupyter-widgets%2Fwidget-cookiecutter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jupyter-widgets","download_url":"https://codeload.github.com/jupyter-widgets/widget-cookiecutter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247217183,"owners_count":20903009,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T21:00:45.937Z","updated_at":"2025-04-04T17:07:17.752Z","avatar_url":"https://github.com/jupyter-widgets.png","language":"JavaScript","funding_links":[],"categories":["Interactive Widgets"],"sub_categories":["Create Your Own Widget with JavaScript"],"readme":"# widget-cookiecutter (deprecated)\n\n## This cookitcutter template is now deprecated\n\n### We recommend [anywidget](https://github.com/manzt/anywidget) as an alternative for those who want to learn or quickly prototype widgets. For production uses, we recommend the [TypeScript cookiecutter](https://github.com/jupyter-widgets/widget-ts-cookiecutter)\n\n#### A cookiecutter template for creating a custom Jupyter widget project\n\n[![Documentation Status](https://readthedocs.org/projects/ipywidgets/badge/?version=latest)](https://ipywidgets.readthedocs.io/en/latest/?badge=latest)\n[![Join the chat at https://gitter.im/jupyter-widgets/Lobby](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/jupyter-widgets/Lobby?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\nA [cookiecutter](https://github.com/audreyr/cookiecutter) template for a custom\nJupyter widget project.\n\n## What is widget-cookiecutter?\n\nWith **widget-cookiecutter** you can create a custom Jupyter interactive\nwidget project with sensible defaults. widget-cookiecutter helps custom widget\nauthors get started with best practices for the packaging and distribution\nof a custom Jupyter interactive widget library.\n\n## Who uses widget-cookiecutter\n\nPopular widget libraries such as\n[bqplot](https://github.com/bloomberg/bqplot),\n[pythreejs](https://github.com/jovyan/pythreejs) and\n[ipyleaflet](https://github.com/ellisonbg/ipyleaflet)\ncan serve as advanced examples of usage of the\nJupyter widget infrastructure.\n\n## Usage\n\nInstall [cookiecutter](https://github.com/audreyr/cookiecutter):\n\n    $ pip install cookiecutter\n\nAfter installing cookiecutter, use the widget-cookiecutter:\n\n    $ cookiecutter https://github.com/jupyter/widget-cookiecutter.git\n\nAs widget-cookiecutter runs, you will be asked for basic information about\nyour custom Jupyter widget project. You will be prompted for the following\ninformation:\n\n- `author_name`: your name or the name of your organization,\n- `author_email`: your project's contact email,\n- `github_project_name`: name of your custom Jupyter widget's GitHub repository,\n- `github_organization_name`: name of your custom Jupyter widget's GitHub user or organization,\n- `python_package_name`: name of the Python \"backend\" package used in your custom widget.\n- `npm_package_name`: name for the npm \"frontend\" package holding the JavaScript\n  implementation used in your custom widget.\n- `project_short_description` : a short description for your project that will\n  be used for both the \"backend\" and \"frontend\" packages.\n\nAfter this, you will have a directory containing files used for creating a\ncustom Jupyter widget. You will now be able to easily package and distribute\nyour custom Jupyter widget.\n\n## Files Generated by cookiecutter\n\nJupyter widgets are composed of two separate programs:\n\n- A Python package for the code executed in notebook kernel as the backend of the widget\n- A Javascript package for the frontend of the widget running in browser\n\nThis cookiecutter generates example source files for both the backend and frontend programs, as well as the tooling to develop and publish the widget in the classic notebook, JupyterLab and in [stand-alone HTML pages](https://ipywidgets.readthedocs.io/en/stable/embedding.html).\n\nRunning the cookiecutter generates the following file tree:\n\n```\n├── \u003cpython_package_name\u003e\n│   ├── __init__.py\n│   ├── _version.py\n│   └── example.py\n├── js\n│   ├── lib\n│   │   ├── embed.js\n│   │   ├── example.js\n│   │   ├── extension.js\n│   │   ├── index.js\n│   │   └── labplugin.js\n│   ├── package.json\n│   ├── README.md\n│   └── webpack.config.js\n├── .gitignore\n├── \u003cnpm_package_name\u003e.json\n├── MANIFEST.in\n├── README.md\n├── RELEASE.md\n├── setup.cfg\n└── setup.py\n```\n\n- **`\u003cpython_package_name\u003e directory`**\\\n  This directory contains the python package that runs in the kernel\n\n      - **`__init__.py`**\\\n\n  Marks the `\u003cpython_package_name\u003e` directory as a python module, allowing `\u003cpython_package_name\u003e` to be imported\n\n      - **`_version.py`**\\\n\n  Contains version definitions for both the backend and the frontend code, to be used from Python. You should not need to modify this file, apart from when you release a new version of the package.\n\n      - **`example.py`**\\\n\n  Example source file containing a widget. Modify this to define your own widgets.\n\n- **`js directory`**\\\n  Source files for widget frontend. There are actually three different frontend programs:\n\n      1. one that is suitable for loading the widget frontend in the classic notebook\n      2. one that is suitable for loading the widget frontend in standalone HTML webpages with no backend\n      3. one that is suitable for loading the widget frontend in JupyterLab\n\n  Fortunately, you don't have to write three different versions of your widgets. There are three entrypoints that all load the widget source files. Each of the frontend program gets bundled using [webpack](https://webpack.js.org/):\n\n      1. The classic notebook frontend bundle gets created using `index.js` as the entrypoint.\n      2. The standalone frontend bundle gets created using `embed.js` as the entrypoint.\n      3. For JupyterLab, the frontend code gets folded into the JupyterLab frontend itself using JupyterLab's webpack. JupyterLab will include `labplugin.js` as the entrypoint to the widgets.\n\n      - **`lib directory`**\\\n\n  Directory containing source files\n\n         - **`embed.js`**\\\n\n  Webpack entry-point for generating the code bundle that is loaded when widgets are used in a stand-alone HTML page. Learn more about embedding widgets into a stand-alone HTML page [here](https://ipywidgets.readthedocs.io/en/stable/embedding.html). When you add new source files to your project that declare widgets, you will need to export them here.\n\n         - **`example.js`**\\\n\n  Widget frontend source code. Contains widget model and view class definitions. Widget model is derived from [DOMWidgetModel](https://github.com/jupyter-widgets/ipywidgets/blob/master/packages/base/src/widget.ts) which provides functionality to communicate with the model instance on kernel. Widget view is derived from [DOMWidgetView](https://github.com/jupyter-widgets/ipywidgets/blob/master/packages/base/src/widget.ts) which has a `model` attribute referencing to widget model it is presenting.\n\n         - **`extension.js`**\\\n\n  Entry-point that is loaded by the classic notebook to load your widget. You should not need to modify this. Note that this does not get included in the webpack bundle.\n\n         - **`index.js`**\\\n\n  This is the entrypoint to your library. When you add new widgets, or change widget names, add these here. When bundling for the classic notebook, webpack will create a single bundle based on this file. This bundle is then loaded by `extension.js`. For JupyterLab, `labplugin.js` loads this file.\n\n         - **`labplugin.js`**\\\n\n  JupyterLab extension definition for JupyterLab integration. When JupyterLab loads, it activates the plugin defined in this file. Widget registry service provided by `@jupyter-widgets/jupyterlab-manager` is used during activation to register the widget with JupyterLab. You should not need to modify this file.\n\n      - **`package.json`**\\\n\n  npm package definiton file for widget frontend. You should not need to modify this file, apart from to add new JavaScript dependencies.\n\n      - **`README.md`**\\\n\n  Auto-generated documentation file for frontend npm package, with installation instructions.\n\n      - **`webpack.config.js`**\\\n\n  Webpack bundler configuration that defines bundler entry points and ouputs along with other configuration\n\n- **`.gitignore`**\\\n  Ignore rules for widget project git repository.\n\n- **`\u003cnpm_package_name\u003e.json`**\\\n  This file gets copied into the configuration directory for the classic notebook as part of the installation process. This enables the extension for the notebook. You should not need to modify this file.\n\n- **`MANIFEST.in`**\\\n  setuptools configuration file containing commands to execute (include / exclude files) during installation (pip install). You should not need to modify this file, unless you change the directory structure for your project.\n\n- **`README.md`**\\\n  Auto-generated documentation file for widget project.\n\n- **`RELEASE.md`**\\\n  Auto-generated documentation file with instructions for publishing python package to PyPI and npm package to npm registry.\n\n- **`setup.cfg`**\\\n  Configuration file to mark the python package as a [Universal Wheel](https://packaging.python.org/guides/distributing-packages-using-setuptools/#universal-wheels).\n\n- **`setup.py`**\\\n  Build script for the widget package. Note that the `setup.py` is heavily customised compared to pure Python packages. In particular, it builds the JavaScript code when creating a source distribution, and copies the notebook frontend into the right directory when a user installs the package.\n\n## Local Dev Installation for Classic Notebook\n\nTo develop this package against the classic notebook, run:\n\n- `pip install -e .` (installs python package for development, runs `npm install` and `npm run build`)\n- `jupyter nbextension install --py --symlink --sys-prefix \u003cpython_package_name\u003e`\\\n  (symlinks `nbextension/` directory into `\u003cjupyter path\u003e/nbextensions/\u003cextension_name\u003e/`). Now the notebook has access to the frontend code.\n- `jupyter nbextension enable --py --sys-prefix \u003cpython_package_name\u003e`\\\n  (copies `\u003cnpm_package_name\u003e.json` into `\u003cenvironment path\u003e/etc/jupyter/nbconfig/notebook.d/` directory). Now the notebook will load your frontend code on page load.\n\nNow make some changes to your source code. Then:\n\n- After making Python code changes, restarting the notebook kernel will be enough to reflect changes\n- After making JavaScript code changes:\n  - `cd js`\n  - `yarn run build`\n  - Refresh browser to reflect changes\n\n## Local Dev Installation for JupyterLab\n\nTo develop this package against JupyterLab, run:\n\n- `pip install -e .` (installs python package for development, runs `yarn install` and `yarn run build` and installs the labextension)\n- `jupyter labextension develop \u003cpython_package_name\u003e --overwrite`\n\nNow make some changes to your source code. Then:\n\n- After making Python code changes, restarting the notebook kernel will be enough to reflect changes\n- After making JavaScript code changes:\n  - `cd js`\n  - `yarn run build`\n  - Refresh browser to reflect changes\n\n## Publishing Widget\n\nFollow the steps in (RELEASE.md) to publish widget python package and npm packages.\n\n## Widget Installation Process for Notebook\n\nWhen installing published package in non-development mode\n\n- `pip install` installs python package for access from kernel and copies frontend code files from `nbextension/` directory into `\u003cjupyter path\u003e/nbextensions/\u003cextension_name\u003e/` and enables by copying `\u003cnpm_package_name\u003e.json` file into `\u003cenvironment path\u003e/etc/jupyter/nbconfig/notebook.d/` directory.\n\n## Widget Load Process for Notebook\n\n- Python code is loaded into kernel from python package directory\n- Frontend javascript code loaded from `\u003cjupyter path\u003e/nbextensions/\u003cextension_name\u003e/extension.js`\n\n## More information\n\n- [Documentation of Jupyter widgets](https://ipywidgets.readthedocs.io/en/latest/)\n- Ask questions about using widget-cookiecutter on the Gitter channel\n- If you find an issue with widget-cookiecutter or would like to contribute an\n  enhancement, [file an issue](https://github.com/jupyter/widget-cookiecutter/issues/new)\n  at the widget-cookiecutter GitHub repo.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjupyter-widgets%2Fwidget-cookiecutter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjupyter-widgets%2Fwidget-cookiecutter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjupyter-widgets%2Fwidget-cookiecutter/lists"}