5 ms·

Show HN: Srcbook – A TypeScript notebook for rapid prototyping

267 points by nichochar 2y ago

Srcbook (”source-book”) is an open-source TypeScript notebook that runs locally, powered by Node.js. It shines for rapid prototyping, code exploration, and collaborating on ideas. It’s inspired by Python’s Jupyter and Elixir’s Livebook. Key features: - Full npm ecosystem access - AI-assisted coding (OpenAI, Anthropic, or local models), it can iterate on the cells for you with a code diff UX that you accept/reject for a given code cell, generate entire Srcbooks, fix compilation issues, etc… - Exports to valid markdown for easy sharing and version control Try it now: `npx srcbook start` Examples Srcbooks to explore: https://hub.srcbook.com https://hub.srcbook.com We built this because we needed a Jupyter-like environment for TypeScript, we hope others like it as much as we do! Feedback and contributions are super appreciated. (edit: formatting)

mlejva 2y ago
This looks interesting. What are some of the coolest srcbooks you have seen so far?
- nichochar 2y ago
  Hey @mlejva, we have mostly been using this internally so far. Some of the coolest use cases are asking it to straight up teach us about something: "I want to learn about Y.js and CRDTs", or "What is a good implementation of a client/server websockets mechanism". Other than that, it's good for shared scripts, things that might otherwise live in your npm scripts. One example is that we use a shared Srcbook to upload data to our Hub.
adamddev1 2y ago
Does this include, or are there plans for MDX/React component support? That would be amazing and I would use it extensively.
- nichochar 2y ago
  This is on our roadmap, yes. We focused on node first because we thought that was missing (you can always spin up a devserver for component), but we'd like to introduce a browser cell which would allow you to add HTMl / JSX components. Can you say a little more about the concrete use case you have? It helps us prioritize
  - thawab 2y ago
    Not OP but i am interested in the same idea to document components. An alternative to storybook.
    - lioeters 2y ago
      Curious, are there features you're missing from storybook, or things you don't like about it?
      - thawab 2y ago
        Srcbook with AI can do the same job faster.
  - adamddev1 2y ago
    It would be nice to do little interactive examples, and React/MDX seems to be the easiest way to do this. I have have a similar thing wired up with https://grammar.lingdocs.com https://grammar.lingdocs.com that allows for interactive components with MDX in a textbook format.
fkilaiwi 2y ago
this is awesome. how do you plan to monetize this?
- nichochar 2y ago
  The plan is to have a cloud offering which runs Srcbooks as infrastructure. There are a couple of directions are considering, but essentially they boil down to helping you build an app quickly and iteratively, then serve it in production. The Srcbook app is meant to be open-source and help drive adoption of the future hosted offerings, and we're focusing on making that useful for now.
jumploops 2y ago
I’ve always wanted a TypeScript-based Jupyter notebook, thanks for building this!
- valstu 2y ago
  I just recently found out that there is Deno kernel for Jupyter notebook https://blog.jupyter.org/bringing-modern-javascript-to-the-jupyter-notebook-fc998095081e https://blog.jupyter.org/bringing-modern-javascript-to-the-j...
xixixao 2y ago
How does it compare with Observable? https://observablehq.com/ https://observablehq.com/
- nichochar 2y ago
  They're both notebooks for TypeScript, but Observable is highly specialized in data visualizations (graphs, plots, etc...) and runs in the browser. Srcbook is built for different use cases: we focus on a backend runtime (node) and want to solve for non-data-visualizations workflows. Use cases like prototyping with a third party npm library, running a script to test your app's behavior, or building an AI agent.
- fsiefken 2y ago
  Compared to Observable, it's apache-2 licensed and it's self-hostable. The d3, p5 and database access you have to add yourself. With Observable user, workspace, diagramming and template management is built-in.
  - nichochar 2y ago
    Yes, these are all great points that I didn't mention, thanks for completing my answer.
  - bsimpson 2y ago
    Isn't Observable also open source? https://github.com/observablehq/runtime https://github.com/observablehq/runtime
- bsimpson 2y ago
  I think this is more like Google Colab, where the UI renders in the browser, but offloads computation to a kernel running elsewhere. As I recall, Observable uses the browser's JS runtime for computation.
bityard 2y ago
Jupyter can run JS kernels these days.
- nichochar 2y ago
  Aware of this, but somehow it seems to miss the mark? It's hard to use third party libraries, and is a little buggy. We asked a lot of devs if they had used it, and often got the answer that they tried it and churned because it wasn't a good experience. Do you use it? Does it work well for you? I'm interested in learning more about your use case if you don't mind sharing.
- turblety 2y ago
  The experience is awful if you don't want any of the Python stuff.
  - nsonha 2y ago
    so you never install any language and tool other than that of js? That's not a realistic expectation in modern software development imo. Just accept it and use the best tool for the job. jupyter is for playing around anyway so the fact that you don't have to think about how it affects production makes it not as complicated as it sounds. You don't need to use the web client, all IDEs have jupyter integration these days, Zed even has it built-in. Just one "pip install" away.
- cmanrt 2y ago
  So? Jupyter is deeply embedded in the Python ecosystem which is a repressive hierarchy run by representatives of some companies as well as some rich people in the scientific ecosystem. People who want to move away from that welcome any alternatives, be it Mathematica or true open source replacements in TypeScript. Please port numpy to TypeScript, too!
ashobeiri 2y ago
This is really cool, looking forward to trying it out. Love the name as well
jwilber 2y ago
I think this really nails a missing sweet spot for frontend/node projects. Observable is a great notebook env for dataviz, but the bespoke js + observability patterns can feel obtuse for non-dataviz stuff. Likewise, the Jupyter js kernels feel second-class and require python dependencies. Really looking forward to using this for documenting open-source and prototyping.
gryzzly 2y ago
Very cool! I wish there was also a "browser" cell, so that the execution wouldn’t be happening in the node.
- nichochar 2y ago
  We keep hearing this, definitely going to prioritize it.
  - gryzzly 2y ago
    nice, most ideal would be if it could work with import maps and standard import statements, so that you could demo stuff easily.
fsiefken 2y ago
Nice, if you could run wasm inline, one could conceivably use it for rust debugging or typst like this: https://github.com/Myriad-Dreamin/typst.ts https://github.com/Myriad-Dreamin/typst.ts Also see this jupyter notebook request https://github.com/typst/typst/issues/962 https://github.com/typst/typst/issues/962
- nichochar 2y ago
  I somehow didn't know about https://github.com/typst/typst https://github.com/typst/typst. This is a really cool project, going to dig in further. At first glance, this seems particularly useful for scientific-style notebooks, which aren't our primary focus. If the demand is there though, I don't see why we couldn't integrate.
mbo 2y ago
I hate to be negative, but I'm not entirely sure why this is advantageous over just dumping a bunch of HTML files into a folder. Why can't the code live in <script type="module">'s with `display: block` tagged, using esm.sh for libraries? Why do we have to use Markdown that has to get transpiled over a format that can be natively consumed by the browser?
- bubblyworld 2y ago
  Presumably this runs in node, rather than the browser, which might have implications for your dependencies (I know esm.sh shims node core dependencies and does fancy transpilation stuff, but why deal with that if you can just run direct on node).
- Sjlver 2y ago
  For a start, it supports TypeScript. And it can install npm packages. And you get all the node.js APIs: for example, you can read/write files on the local hard drive.
h1fra 2y ago
Very nice, how do you run the code? is it securely sandboxed?
- nichochar 2y ago
  The code runs locally on your machine. Right now the architecture is that each Srcbook has 2 representations: - a markdown encoding that we use when you export. Easier to share, serialize, etc... - on disk, Srcbooks are actually directories under ~/.srcbook/srcbooks. The files and code is all there, and runs with your local node executable. You therefore need to be careful to not run any arbitrary srcbook you download, but there is no code ever leaving your machine
mcintyre1994 2y ago
This is a cool idea! I often end up just using replit to play with a library, something more like Livebook makes a lot of sense. I like that you're using markdown too, makes these files much more useful than Jupyter ones.
- nichochar 2y ago
  Thanks! Yes when we asked people what they used to prototype, we got the weirdest answers. Replit seems very heavyweight, and isn't local (always feels worse). For non-npm things, we heard that a lot of people open up a browser console to use it as a REPL. I think we can do better, hoping Srcbook can cover these use cases well. The Markdown is a really neat idea borrowed from Livebook. It allows for really good diffing if you want to version control them, and makes reviewing diffs easier. As a bonus a lot of things can read markdown and render it nicely for you.
- SebastianKra 2y ago
  Jupyter supports MD, or is that another thing that DataSpell added on top of it?
  - mcintyre1994 2y ago
    I haven't used it for a while, but last time I did it had a pretty horrible not very diff-friendly JSON serialization format. They definitely could have changed that though!
bilalq 2y ago
Love that this is local. I've messed around trying to get Node on Jupyter with custom kernels, but never got close to a working setup with TypeScript. Two features would be huge: 1. Web cells for intermixing UI components alongside NodeJS cells. Would be cool if there was a bridge API to call code in the Node cells as well. 2. VSCode extension to render this all in there directly.
- adius 2y ago
  If you don't mind using Deno instead of Node, it's integrated Jupyter Kernel makes it really easy: https://docs.deno.com/runtime/manual/tools/jupyter/ https://docs.deno.com/runtime/manual/tools/jupyter/
  - bilalq 2y ago
    Oh, that's really interesting. I still use Node for everything and haven't really given Deno a shot, but I'm someone who prefers to stay away from bleeding edge things until they become battle-tested. But with recent NodeJS compatibility changes, this may be really cool for a lot of use-cases.
tcsenpai 2y ago
Very nice. I am trying using ollama with it, looks like something is off either on my server or in the way the program calls it: I get the CPU used instead of the GPU (while using ollama in other apps doesn't). Anyway, impressive
prophesi 2y ago
To those concerned about the analytics like myself, you should be able to turn it off by setting the default here to false. Otherwise you'd need to toggle it off in the settings, which gives ample time for telemetry to fire. https://github.com/srcbookdev/srcbook/blob/ddda46a0b1249c3d7cddee2c3d10baec8db274df/packages/api/db/schema.mts#L12 https://github.com/srcbookdev/srcbook/blob/ddda46a0b1249c3d7...
- blorenz 2y ago
  Comment above linked line states // Allows us to improve Srcbook, we don't collect any PII. I ask that you please consider assisting developers improve their FOSS - free as in beer.
- benjreinhart 2y ago
  We collect a very small amount of analytics (with zero PII attached) which gives us an idea of what people use or don't use. That helps us know where best to spend our time. That said, we hear you. I just added support for disabling all analytics with an environment variable `SRCBOOK_DISABLE_ANALYTICS=true`. See https://github.com/srcbookdev/srcbook/pull/191 https://github.com/srcbookdev/srcbook/pull/191.
  - prophesi 2y ago
    I appreciate that! A decent compromise I've found that would still result in most users consenting to analytics is to have it disabled initially, but on app startup a screen or modal displays the rationale for collecting data alongside a checkbox to opt-in and save their preference. And they could still go to the settings page to toggle it later, as it works now. If it's a hobby project or backed by a small team, even I would opt-in to help the devs out after some trust in the project is established.
    - benjreinhart 2y ago
      We're still in the very early stages of rolling this out (alpha), so I'm not going to overthink it right now given we have a solution to disabling it. But I think your proposal might be a good idea once we come out of alpha, so I'll put that in our roadmap. Very much appreciate the feedback
gabrielcsapo 2y ago
Really awesome to see this stuff continued to be worked on. I had a small project I worked on almost a decade ago https://github.com/gabrielcsapo/node-notebook https://github.com/gabrielcsapo/node-notebook, things have gotten so much better.
aabbcc1241 2y ago
The examples are complete programs. Can I let-declare an variable in one code block, and refer to it in another code block with static type hint?

267 points by nichochar 2y ago

mlejva 2y ago

This looks interesting. What are some of the coolest srcbooks you have seen so far?

nichochar 2y ago
Hey @mlejva, we have mostly been using this internally so far. Some of the coolest use cases are asking it to straight up teach us about something: "I want to learn about Y.js and CRDTs", or "What is a good implementation of a client/server websockets mechanism". Other than that, it's good for shared scripts, things that might otherwise live in your npm scripts. One example is that we use a shared Srcbook to upload data to our Hub.

adamddev1 2y ago

Does this include, or are there plans for MDX/React component support? That would be amazing and I would use it extensively.

nichochar 2y ago
This is on our roadmap, yes. We focused on node first because we thought that was missing (you can always spin up a devserver for component), but we'd like to introduce a browser cell which would allow you to add HTMl / JSX components. Can you say a little more about the concrete use case you have? It helps us prioritize
- thawab 2y ago
  Not OP but i am interested in the same idea to document components. An alternative to storybook.
  - lioeters 2y ago
    Curious, are there features you're missing from storybook, or things you don't like about it?
    - thawab 2y ago
      Srcbook with AI can do the same job faster.
- adamddev1 2y ago
  It would be nice to do little interactive examples, and React/MDX seems to be the easiest way to do this. I have have a similar thing wired up with https://grammar.lingdocs.com https://grammar.lingdocs.com that allows for interactive components with MDX in a textbook format.

fkilaiwi 2y ago

this is awesome. how do you plan to monetize this?

nichochar 2y ago
The plan is to have a cloud offering which runs Srcbooks as infrastructure. There are a couple of directions are considering, but essentially they boil down to helping you build an app quickly and iteratively, then serve it in production. The Srcbook app is meant to be open-source and help drive adoption of the future hosted offerings, and we're focusing on making that useful for now.

jumploops 2y ago

I’ve always wanted a TypeScript-based Jupyter notebook, thanks for building this!

valstu 2y ago
I just recently found out that there is Deno kernel for Jupyter notebook https://blog.jupyter.org/bringing-modern-javascript-to-the-jupyter-notebook-fc998095081e https://blog.jupyter.org/bringing-modern-javascript-to-the-j...

xixixao 2y ago

How does it compare with Observable? https://observablehq.com/ https://observablehq.com/

nichochar 2y ago
They're both notebooks for TypeScript, but Observable is highly specialized in data visualizations (graphs, plots, etc...) and runs in the browser. Srcbook is built for different use cases: we focus on a backend runtime (node) and want to solve for non-data-visualizations workflows. Use cases like prototyping with a third party npm library, running a script to test your app's behavior, or building an AI agent.
fsiefken 2y ago
Compared to Observable, it's apache-2 licensed and it's self-hostable. The d3, p5 and database access you have to add yourself. With Observable user, workspace, diagramming and template management is built-in.
- nichochar 2y ago
  Yes, these are all great points that I didn't mention, thanks for completing my answer.
- bsimpson 2y ago
  Isn't Observable also open source? https://github.com/observablehq/runtime https://github.com/observablehq/runtime
bsimpson 2y ago
I think this is more like Google Colab, where the UI renders in the browser, but offloads computation to a kernel running elsewhere. As I recall, Observable uses the browser's JS runtime for computation.

bityard 2y ago

Jupyter can run JS kernels these days.

nichochar 2y ago
Aware of this, but somehow it seems to miss the mark? It's hard to use third party libraries, and is a little buggy. We asked a lot of devs if they had used it, and often got the answer that they tried it and churned because it wasn't a good experience. Do you use it? Does it work well for you? I'm interested in learning more about your use case if you don't mind sharing.
turblety 2y ago
The experience is awful if you don't want any of the Python stuff.
- nsonha 2y ago
  so you never install any language and tool other than that of js? That's not a realistic expectation in modern software development imo. Just accept it and use the best tool for the job. jupyter is for playing around anyway so the fact that you don't have to think about how it affects production makes it not as complicated as it sounds. You don't need to use the web client, all IDEs have jupyter integration these days, Zed even has it built-in. Just one "pip install" away.
cmanrt 2y ago
So? Jupyter is deeply embedded in the Python ecosystem which is a repressive hierarchy run by representatives of some companies as well as some rich people in the scientific ecosystem. People who want to move away from that welcome any alternatives, be it Mathematica or true open source replacements in TypeScript. Please port numpy to TypeScript, too!

ashobeiri 2y ago

This is really cool, looking forward to trying it out. Love the name as well

jwilber 2y ago

I think this really nails a missing sweet spot for frontend/node projects. Observable is a great notebook env for dataviz, but the bespoke js + observability patterns can feel obtuse for non-dataviz stuff. Likewise, the Jupyter js kernels feel second-class and require python dependencies. Really looking forward to using this for documenting open-source and prototyping.

gryzzly 2y ago

Very cool! I wish there was also a "browser" cell, so that the execution wouldn’t be happening in the node.

nichochar 2y ago
We keep hearing this, definitely going to prioritize it.
- gryzzly 2y ago
  nice, most ideal would be if it could work with import maps and standard import statements, so that you could demo stuff easily.

fsiefken 2y ago

Nice, if you could run wasm inline, one could conceivably use it for rust debugging or typst like this: https://github.com/Myriad-Dreamin/typst.ts https://github.com/Myriad-Dreamin/typst.ts Also see this jupyter notebook request https://github.com/typst/typst/issues/962 https://github.com/typst/typst/issues/962

nichochar 2y ago
I somehow didn't know about https://github.com/typst/typst https://github.com/typst/typst. This is a really cool project, going to dig in further. At first glance, this seems particularly useful for scientific-style notebooks, which aren't our primary focus. If the demand is there though, I don't see why we couldn't integrate.

mbo 2y ago

I hate to be negative, but I'm not entirely sure why this is advantageous over just dumping a bunch of HTML files into a folder. Why can't the code live in <script type="module">'s with `display: block` tagged, using esm.sh for libraries? Why do we have to use Markdown that has to get transpiled over a format that can be natively consumed by the browser?

bubblyworld 2y ago
Presumably this runs in node, rather than the browser, which might have implications for your dependencies (I know esm.sh shims node core dependencies and does fancy transpilation stuff, but why deal with that if you can just run direct on node).
Sjlver 2y ago
For a start, it supports TypeScript. And it can install npm packages. And you get all the node.js APIs: for example, you can read/write files on the local hard drive.

h1fra 2y ago

Very nice, how do you run the code? is it securely sandboxed?

nichochar 2y ago
The code runs locally on your machine. Right now the architecture is that each Srcbook has 2 representations: - a markdown encoding that we use when you export. Easier to share, serialize, etc... - on disk, Srcbooks are actually directories under ~/.srcbook/srcbooks. The files and code is all there, and runs with your local node executable. You therefore need to be careful to not run any arbitrary srcbook you download, but there is no code ever leaving your machine

mcintyre1994 2y ago

This is a cool idea! I often end up just using replit to play with a library, something more like Livebook makes a lot of sense. I like that you're using markdown too, makes these files much more useful than Jupyter ones.

nichochar 2y ago
Thanks! Yes when we asked people what they used to prototype, we got the weirdest answers. Replit seems very heavyweight, and isn't local (always feels worse). For non-npm things, we heard that a lot of people open up a browser console to use it as a REPL. I think we can do better, hoping Srcbook can cover these use cases well. The Markdown is a really neat idea borrowed from Livebook. It allows for really good diffing if you want to version control them, and makes reviewing diffs easier. As a bonus a lot of things can read markdown and render it nicely for you.
SebastianKra 2y ago
Jupyter supports MD, or is that another thing that DataSpell added on top of it?
- mcintyre1994 2y ago
  I haven't used it for a while, but last time I did it had a pretty horrible not very diff-friendly JSON serialization format. They definitely could have changed that though!

bilalq 2y ago

Love that this is local. I've messed around trying to get Node on Jupyter with custom kernels, but never got close to a working setup with TypeScript. Two features would be huge: 1. Web cells for intermixing UI components alongside NodeJS cells. Would be cool if there was a bridge API to call code in the Node cells as well. 2. VSCode extension to render this all in there directly.

adius 2y ago
If you don't mind using Deno instead of Node, it's integrated Jupyter Kernel makes it really easy: https://docs.deno.com/runtime/manual/tools/jupyter/ https://docs.deno.com/runtime/manual/tools/jupyter/
- bilalq 2y ago
  Oh, that's really interesting. I still use Node for everything and haven't really given Deno a shot, but I'm someone who prefers to stay away from bleeding edge things until they become battle-tested. But with recent NodeJS compatibility changes, this may be really cool for a lot of use-cases.

tcsenpai 2y ago

Very nice. I am trying using ollama with it, looks like something is off either on my server or in the way the program calls it: I get the CPU used instead of the GPU (while using ollama in other apps doesn't). Anyway, impressive

prophesi 2y ago

To those concerned about the analytics like myself, you should be able to turn it off by setting the default here to false. Otherwise you'd need to toggle it off in the settings, which gives ample time for telemetry to fire. https://github.com/srcbookdev/srcbook/blob/ddda46a0b1249c3d7cddee2c3d10baec8db274df/packages/api/db/schema.mts#L12 https://github.com/srcbookdev/srcbook/blob/ddda46a0b1249c3d7...

blorenz 2y ago
Comment above linked line states // Allows us to improve Srcbook, we don't collect any PII. I ask that you please consider assisting developers improve their FOSS - free as in beer.
benjreinhart 2y ago
We collect a very small amount of analytics (with zero PII attached) which gives us an idea of what people use or don't use. That helps us know where best to spend our time. That said, we hear you. I just added support for disabling all analytics with an environment variable `SRCBOOK_DISABLE_ANALYTICS=true`. See https://github.com/srcbookdev/srcbook/pull/191 https://github.com/srcbookdev/srcbook/pull/191.
- prophesi 2y ago
  I appreciate that! A decent compromise I've found that would still result in most users consenting to analytics is to have it disabled initially, but on app startup a screen or modal displays the rationale for collecting data alongside a checkbox to opt-in and save their preference. And they could still go to the settings page to toggle it later, as it works now. If it's a hobby project or backed by a small team, even I would opt-in to help the devs out after some trust in the project is established.
  - benjreinhart 2y ago
    We're still in the very early stages of rolling this out (alpha), so I'm not going to overthink it right now given we have a solution to disabling it. But I think your proposal might be a good idea once we come out of alpha, so I'll put that in our roadmap. Very much appreciate the feedback

gabrielcsapo 2y ago

Really awesome to see this stuff continued to be worked on. I had a small project I worked on almost a decade ago https://github.com/gabrielcsapo/node-notebook https://github.com/gabrielcsapo/node-notebook, things have gotten so much better.

aabbcc1241 2y ago

The examples are complete programs. Can I let-declare an variable in one code block, and refer to it in another code block with static type hint?