thebe 0.9.0 release plan

[stevejpurves]

Context

Currently, new work on thebe is happening in this branch: https://github.com/executablebooks/thebe/tree/feat/integrate-thebe-core

Once that is merged there will be three packages distributed by this repository:

• thebe-core (packages/core): Meant for developers. Will contain the low-level APIs for interacting with Thebe, the Jupyter server, etc. It is designed for those who wish to have full control over how Thebe works and want to implement their own UI (e.g. to build its functionality into their own app or custom page).
• thebe (packages/thebe): Meant for users and downstream consumers. Will contain the thebe.js application that people have been using up to now. This should be close to a "drop in and it just works" solution for most people, and is what we'd use in sphinx-thebe for use in Jupyter Book.
• thebe-lite (packages/lite): An optional drop-in library that can be used with thebe or thebe-core, extending them with a JupyterLite distribution bundled inside to be workable with pure javascript and WASM

There are also two sets of documentation

• docs (apps/docs): for end users based on a refresh of the current content with additional info on configuration and thebe-lite usage
• docs-core (apps/docs-core): documenting core and lite features in detail for developers

Where and how there documentation is to be deployed is TBD, e.g. the two sets might be combined into/hosted on a single site

0.9.0 Release

Setting out what we want to do ahead of and as part of the 0.9.0 release

blocking issues

• [ ] complete the checklist on the PR
• [ ] thebe run buttons need to be updated in order to block / queue execution when kernel is not ready (or provide a new but equivalent UX to the "Waiting on kernel...")
• [ ] testing via release candidates!
• [ ] build and test with sphinx-thebe

### General Todos

• [x] rename master to main
• [x] create a 0.8.x branch from latest main
• [x] merge integrate-thebe-core branch into main
• [ ] finalize a set of documentation for thebe-core aimed at js/ts app/page developers
• [ ] update/improve the thebe documentation aimed at end users
  • [ ] make it easier to understand the options available and have one source of truth
  • [ ] add a section on jupyterlite
• [ ] update thebe sphinx-based docs
  • [ ] ensure existing thebe docs build
  • [ ] add docs on thebe-core
  • [ ] add docs on thebe-lite
  • [ ] add docs for enabling thebe-lite on a page
• [ ] update readme in lite repo
• [ ] update demo-core to use typescript interfaces fully

Post Release /. Launch

• A blog post
• ...

[choldgraf]

Here's my understanding of how these repositories will work moving forward:

• Currently, new work on thebe is happening in this branch: https://github.com/executablebooks/thebe/tree/feat/integrate-thebe-core
• Once that is merged there will be three packages distributed by this repository:
  • thebe-core/: Meant for developers. Will contain the low-level APIs for interacting with Thebe, the Jupyter server, etc. It is designed for those who wish to have full control over how Thebe works (e.g. to build its functionality into their own app).
  • thebe/: Meant for users and downstream consumers. Will contain the thebe.js application that people have been using up to now. This should be close to a "drop in and it just works" solution for most people, and is what we'd use in sphinx-thebe for use in Jupyter Book.
  • thebe-light/: A distribution of thebe for use with jupyterlite. This is a special-case of the thebe/ distribution described above, with a JupyterLite distribution bundled inside to be workable with pure javascript and WASM

[psychemedia]

@choldgraf thebe-lite not thebe-light?

Is the lite package a replacement for thebe.js or a plugin/extension for it? For use with Jupyterlite do you need both packages or just the lite one?

Also, JupyterLite is a UI + the "server" / WASM kernel. For thebe, presumably there is no need to load in the UI components (JupyterLab etc) though there will be a need to have a Jupyter kernel "server" / client to interact with the kernel? (Presumably, a native Pyodide thebe client would be simpler and could directly interact with a Pyodide py environment, for example?)

[stevejpurves]

@psychemedia I used @choldgraf 's comment to expand the issue description -- thanks @choldgraf!

The thebe-lite package should loaded as well as thebe. (That is best explained here atm https://github.com/executablebooks/thebe/blob/feat/integrate-thebe-core/packages/lite/README.md, docs need to improve)

You are not going to be able to pull [thebe-lite] from unpkg.com though, I think you'll need to host the whole thing including the wheels, and make them available on specific paths on your domain. (this requires planned/future changes to pyolite to do anything about)

If you want less juptyerlab UI, then you can look at using thebe-core alone, and develop against the typescript API. Note that it still loads pieces of juptyerlab, and there might be some scope to minimise this over time (with upstream changes).

@psychemedia is it bundle size that's your concern here?

In terms of jupyter server vs plain pyodide - using a plain pyodide integration would likely be simpler, however without additional work to run in a web worker would be working on the main thread. Othere benefits of integrating via jlite/pyolite is that you get the kernel running in a web worker already, have package loading via pipelite and down the line can take advantage of different WASM kernels that pyolite/jupyterlite will support -- in python and other languages.

The biggest issue for deploying this at the moment could be these fixed paths for the wheels -- requiring you to host the whole thebe-lite module. There may be a way to get it working against unpkg.com but I think that would require path rewriting or proxying and the like -- or at least be hosting specific config.

Note: current URL for thebe on unpkg.com is https://unpkg.com/[email protected]/lib/index.js and matching version of thebe-lite on npm is 0.1.0

[psychemedia]

The extra weight of loading in JupyterLab does seem like an unnecessary overhead, unless an "open in JupyterLite" option is also being offered that justifies the download.

[stevejpurves]

it is not the whole of jupyerlab, only portions of it though -- although some of those packages could be removed from the bundle but some restructuring upstream in jupyerlab, in some cases we are using jupyterlab components for rendering thebe outputs.

[kurshakuz]

Hey!

I have tried to use thebe-core in my NextJS application, and got stuck with the following error:

./node_modules/@jupyter-widgets/base/css/index.css
Global CSS cannot be imported from within node_modules.
Read more: https://nextjs.org/docs/messages/css-npm
Location: node_modules/@jupyter-widgets/jupyterlab-manager/lib/plugin.js

Basically, what I tried to do is to first install the package via npm i thebe-core, and then call the makeConfiguration in my component. Do you know if I am missing something?

import { makeConfiguration } from 'thebe-core';
  ...
  const config = makeConfiguration({ useBinder: true });

[stevejpurves]

Hi @kurshakuz, interesting - btw i've not run or tested with next.js, I have with remix.run which is also doing SSG/SSR but obviously different constraints. Would you mind opening a separate issue on the repo for this one as we can discuss there? (btw as first heads up -- I need to asynchronously load the thebe-core package for remix i.e. await import('thebe-core)` and ensure it's in clientSideOnly code)

[kurshakuz]

Hi @kurshakuz, interesting - btw i've not run or tested with next.js, I have with remix.run which is also doing SSG/SSR but obviously different constraints. Would you mind opening a separate issue on the repo for this one as we can discuss there?

Sure! Just opened one here: https://github.com/executablebooks/thebe/issues/589. Let me know if you need any help with testing

(btw as first heads up -- I need to asynchronously load the thebe-core package for remix i.e. await import('thebe-core)` and ensure it's in clientSideOnly code)

I will try testing this approach and let you know