Package: jupyterlab-examples-hello-world
Hello WorldSet up the development environment and print to the console.The template folder structureA minimal extension that prints to the browser consoleBuilding and Installing an ExtensionThe template folder structureWriting a JupyterLab extension usually starts from a configurable template. It
can be downloaded with thecookiecuttertool and the following command:cookiecutterhttps://github.com/jupyterlab/extension-cookiecutter-tscookiecutterasks for some basic information that could for example be setup
like this:author_name[]:tuto
author_email[]:tuto@help.you
labextension_name[myextension]:hello-world
python_name[hello_world]:
project_short_description[AJupyterLabextension.]:MinimalJupyterLabexample
has_settings[n]:
has_server_extension[n]:
has_binder[n]:y
repository[https://github.com/github_username/hello-world]:The python name should not contain-. It is nice for user to test your extension online, so thehas_binderwas set toyes.The cookiecutter creates the directoryhello_world[or your extension name]
that looks like this:hello_world/
│.eslintignore
│.eslintrc.js
│.gitignore
│.prettierignore
│.prettierrc
│install.json
│LICENSE
│MANIFEST.in
│package.json
│pyproject.toml
│README.md
│setup.py
│tsconfig.json
│
├───.github
│└───workflows
│build.yml
│
├───binder
│environment.yml
│postBuild
│
├───hello_world
│__init__.py
│_version.py
│
├───src
│index.ts
│
└───stylebase.cssindex.cssindex.jsThose files can be separated in 4 groups:Information about the extension:README.mdcontains some instructionsLICENSEcontains your extension code license; BSD-3 Clause by default (but you can change it).Extension code (those files are mandatory):package.jsoncontains information about the extension such as dependenciestsconfig.jsoncontains information for the typescript compilationsrc/index.tsthis contains the actual code of your extensionstyle/folder contains style elements that you can useValidation:.prettierrcand.prettierignorespecify the code formatterprettierconfiguration.eslintrc.jsand.eslintignorespecify the code lintereslintconfiguration.github/workflows/build.ymlsets the continuous integration tests of the code usingGitHub ActionsPackaging as a Python package:setup.pycontains information about the Python package such as what to packagepyproject.tomlcontains the dependencies to create the Python packageMANIFEST.incontains list of non-Python files to include in the Python packageinstall.jsoncontains information retrieved by JupyterLab to help users know how to manage the packagehello_world/folder contains the final code to be distributedThe following sections will walk you through the extension code files.A minimal extension that prints to the browser consoleStart with the filesrc/index.ts. This typescript file contains the main
logic of the extension. It begins with the following import section:// src/index.ts#L1-L4import{JupyterFrontEnd,JupyterFrontEndPlugin,}from'@jupyterlab/application';JupyterFrontEndis the main Jupyterlab application class. It allows you to
access and modify some of its main components.JupyterFrontEndPluginis the class
of the extension that you are building. Both classes are imported from a package
called@jupyterlab/application. The dependency of your extension on this
package is declared in the filepackage.json:// package.json#L49-L51

"dependencies": {
  "@jupyterlab/application": "^3.1.0"
},With this basic import setup, you can move on to construct a new instance
of theJupyterFrontEndPluginclass:// src/index.ts#L9-L12constplugin:JupyterFrontEndPlugin<void>={id:'hello-world:plugin',autoStart:true,activate:(app:JupyterFrontEnd)=>{console.log('JupyterLab extension hello-world is activated!');// src/index.ts#L14-L17},};exportdefaultplugin;AJupyterFrontEndPlugincontains a few attributes:id: the unique id of the extensionautoStart: a flag to start the extension automatically or notactivate: a
function (() => {}notation) that takes one argumentappof typeJupyterFrontEndand will be called by the main application to activate the extension.appis the main JupyterLab application. Theactivatefunction acts as an entry
point into the extension. In this example, it calls theconsole.logfunction to output
something into the browser developer tools console.Your newJupyterFrontEndPlugininstance has to be finally exported to be visible to
JupyterLab, which is done with the lineexport default plugin.Now that the extension code is ready, you need to install it within JupyterLab.Building and Installing an ExtensionThese are the instructions on how your extension can be installed for development:You will need NodeJS to build the extension package.# Install package in development modepipinstall-e.# Link your development version of the extension with JupyterLabjupyterlabextensiondevelop.--overwrite# Rebuild extension Typescript source after making changesjlpmrunbuildThejlpmcommand is JupyterLab's pinned version ofyarnthat is installed with JupyterLab. You may useyarnornpmin lieu ofjlpmbelow.The first command installs the dependencies that are specified in thesetup.pyfile and inpackage.json. Among the dependencies are also all of theJupyterLabcomponents that you want to use in your project.It then runs the build script. In that step, the TypeScript code gets
converted to javascript using the compilertscand stored in alibdirectory. And a condensed form of the Javascript is copied in the Python
package (in the folderhello_world/labextension). This is the code that
would be installed by the user in JupyterLab.The second command create a symbolic link to the folderhello_world/labextensionso that extension is installed in development mode in JupyterLab.The third command allows you to update the Javascript code each time you modify your
extension code.After all of these steps are done, runningjupyter labextension listshould
show something like:localextensions:@jupyterlab-examples/hello-world:[...]/hello-worldNow let's check inside of JupyterLab if it works. Run [can take a while]:jupyterlab--watchYour extension writes something to the browser console. In most web browsers you can
open the console pressing theF12key. You should see something like:JupyterLab extension hello-world is activatedYour extension works but it is not doing much. Let's modify the source code
a bit. Simply replace theactivatefunction with the following lines:// src/index.ts#L12-L14activate:(app:JupyterFrontEnd)=>{console.log('the JupyterLab main application:',app);},To update the module, simply go to the extension directory and runjlpm buildagain. Since you used the--watchoption when starting
JupyterLab, you just have to refresh the JupyterLab website in the browser
and should see in the browser console:the JupyterLab main application:
Object { _started: true, _pluginMap: {…}, _serviceMap: Map(...), _delegate: {…}, commands: {…}, contextMenu: {…}, shell: {…}, registerPluginErrors: [], _dirtyCount: 0, _info: {…}, … }This is the main application JupyterLab object and you will see how to interact
with it in the other examples.Checkout how the core packages of JupyterLab are definedon this page. Each package is
structured similarly to the extension that you are writing. This modular
structure makes JupyterLab very adaptable.An overview of the classes and their attributes and methods can be found in the
JupyterLab documentation. The@jupyterlab/applicationmodule documentation ishereand here is theJupyterFrontEnd class documentation.Where to Go NextJupyterLab is built on top of three major concepts. It is advised to look through the corresponding
examples in the following order:command: Function to be executed from UI elements. See thecommands examplewidget: UI based brick. See thewidgets examplesignal: Observer pattern between JupyterLab elements. See thesignals example