{"id":13424692,"url":"https://github.com/jonklein/niex","last_synced_at":"2025-04-06T19:13:27.990Z","repository":{"id":54645626,"uuid":"322704261","full_name":"jonklein/niex","owner":"jonklein","description":"Niex is an interactive Elixir code notebook built with Phoenix LiveView.","archived":false,"fork":false,"pushed_at":"2021-02-06T07:56:41.000Z","size":2824,"stargazers_count":419,"open_issues_count":2,"forks_count":15,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-03-30T18:08:28.072Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jonklein.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-12-18T21:04:38.000Z","updated_at":"2024-09-22T17:10:03.000Z","dependencies_parsed_at":"2022-08-13T22:40:29.929Z","dependency_job_id":null,"html_url":"https://github.com/jonklein/niex","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonklein%2Fniex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonklein%2Fniex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonklein%2Fniex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonklein%2Fniex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jonklein","download_url":"https://codeload.github.com/jonklein/niex/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247535520,"owners_count":20954576,"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-31T00:00:57.938Z","updated_at":"2025-04-06T19:13:27.964Z","avatar_url":"https://github.com/jonklein.png","language":"Elixir","funding_links":[],"categories":["Elixir"],"sub_categories":["Phoenix"],"readme":"# Niex - Interactive Elixir Code Notebooks\n\nNiex is an interactive Elixir code notebook with support for embedded media and \ncharting, built with Phoenix LiveView.  Niex stores your data \u0026 code in persistent, interactive notebooks, making it great for scientific and \ndata analysis applications using Elixir, or for sharing visual, interactive demos and documentation of code\nwritten in Elixir. \n\n![An animation of a Niex notebook  in action](https://github.com/jonklein/niex/blob/master/sample_notebooks/demo.gif?raw=true)\n\nNiex is inspired by the powerful and full-featured [Jupyter](https://jupyter.org/) project. You may note that Jupyter \n(with some effort) can already support Elixir as a backend, so what's the advantage of using \nNiex?  The main advantage is that Niex is simple, lightweight and written fully in Elixir, so it's easy to use as a simple \ndependency to integrate with your existing Elixir code.  It can be run as a standalone\nPhoenix app, or embedded in your own Elixir project. \n\n## Getting Started\n\nThere are two main ways to run Niex: as a standalone Phoenix app, or embedded as a dependency in your own code base. \n\n### Running Niex standalone server\n\nIf you're looking to get started quickly with Niex, you can clone the Niex repo from GitHub and run as a simple \nPhoenix app:\n\n```\ngit clone https://github.com/jonklein/niex.git\ncd niex\nmix deps.get\n(cd assets; yarn)\nmix phx.server\n```\n\nThen open `http://localhost:4000` to use the notebook.\n\n### Embedding Niex in your own Elixir project\n\nIf you'd like to use Niex in your own Elixir project, and use your own codebase in your notebooks, you can install \nNiex as a dependency:\n\n```\n  defp deps do\n    [\n       {:niex, git: \"https://github.com/jonklein/niex\"}\n    ]\n  end\n```\n\nYou will then need to configure Niex in your `config.exs` with a minimal Phoenix configuration:\n\n```\nconfig :phoenix, :json_library, Poison\n\n# Configures the endpoint\nconfig :niex, NiexWeb.Endpoint,\n  pubsub_server: Niex.PubSub,\n  live_view: [signing_salt: \"xxxxxxxxxxxx\"],\n  secret_key_base: \"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\n  server: true,\n  debug_errors: true,\n  check_origin: false,\n  http: [port: 3333],\n  debug_errors: true,\n  check_origin: false\n```\n\nNote: Though Niex uses Phoenix and LiveView, it runs as its own server on its own port and can be run happily alongside\nyour own Phoenix app.  Configure the Niex port number accordingly to avoid conflicts with the rest of your \nproject - in the example above, we use port 3333. \n\n### Basic Usage\n\nNiex notebooks support two types of cells: code and markdown.\n\nMarkdown cells are used for human-readable text using the [Markdown format](https://www.markdownguide.org/basic-syntax/).\n\nCode cells are used to store \u0026 execute Elixir code.  To use a code cell, simply populate the cell and execute it using \nthe \"run\" button (or the key combo command-retrun).  The cell output field will display the result of the execution.  \nCells must be explicity executed - if you make changes to code that other cells are dependent on, you must explicitly \nrerun those cell commands in order.   \n\n#### Notebook \u0026 Interpreter State\n\nLike running an IEx session, Niex maintains an internal interpreter state that is **independent of the order\nof commands in the notebook**, and **is not saved in the notebook**.  This means that when you open a saved \nnotebook, you must execute each cell in order to restore internal state.  \n\n#### Asynchronous execution \u0026 animation\n\nYou can also display intermediate results for long-running code in cells.  This allows you\nto create animations or updates for asynchronous processes.  To render an intermediate result\nbefore the cell execution is complete, use `Niex.Render/1` with the content.\n\nIn this example, we render an animated sine-wave chart:\n\n```\nfor j \u003c- (1..300) do\n  Process.sleep(30)\n  data = (1..50) |\u003e Enum.map(fn i -\u003e [i, :math.sin(i / 3.0 + j / 10.0)] end)\n  Niex.render(Niex.Content.chart(\"LineChart\", data, %{points: false}))\nend\n\n\"Click run to animate\"\n``` \n\n### Cell Output Display \u0026 Media\n\nBy default, Niex displays the \"inspect\" string of any output.  This is most useful\nfor looking at raw Elixir data including complex data like maps, lists \u0026 structs.\n\nYou can also control the display of output with `Niex.Content` functions.  Niex supports \nHTML, preformatted text, images, video and chart content in notebooks:\n\n```\n# Render HTML\nNiex.Content.html(\"\u003ch1\u003eHello, World\u003c/h1\u003e\")\n\n# Render preformatted text\nNiex.Content.pre(\"# This is a code comment\")\n\n# Render an image\nimage_url = \"https://placekitten.com/408/287\"\nNiex.Content.image(image_url)\n\n# Render a video\nvideo_url = \"http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4\"\nNiex.Content.video(video_url)\n\n# Render a line chart: \ndata = (1..30) |\u003e Enum.map(fn i -\u003e [i, :math.sin(i)] end)\nNiex.Content.chart(\"LineChart\", data, height: 400)\n\n# Render a pie chart: \ndata = %{\"Elixir\" =\u003e 80, \"JavaScript\" =\u003e 10, \"Ruby\" =\u003e 20}\nNiex.Content.chart(\"PieChart\", data, height: 400)\n```\n\nNiex uses the [Chartkick](https://chartkick.com) library for charting, and many other \nchart types are available.  See the [Chartkick JavaScript documentation](https://github.com/ankane/chartkick.js) for \na full list.\n\n### Notebook format\n\nNotebooks are stored in a JSON format generally inspired by the Jupyter notebook format, but greatly simplified.  \n\nSample notebook:\n\n```\n{\n  \"metadata\": { \"name\": \"New Notebook\", \"version\": \"1.0\" },\n  \"worksheets\": {\n    \"cells\": [\n      %{\n        \"cell_type\": \"markdown\",\n        \"content\": [\"# Welcome to Niex\"]\n      }, %{\n        \"cell_type\": \"code\",\n        \"content\": [\"IO.inspect(\\\"123\\\")\"],\n        \"output\": [{\"text\" =\u003e 123}]\n      }\n    ],\n  } \n}\n\n```\n\n## Known issues / future improvements \n\n- executed code is **not** sandboxed - see section below on arbitrary code execution\n- future work - add support for other media types\n- notebook format \u0026 details are subject to change\n\n## WARNING: arbitrary code execution\n\nThis software enables arbitrary code execution **by design** – it is intended for **development and local use only**.  If you\nchoose to expose any Niex functionality over a network, you are responsible for\nimplementing the necessary authorization and access controls. \n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonklein%2Fniex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonklein%2Fniex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonklein%2Fniex/lists"}