# @snap-fileio/extension

> Snap! extension that lets Snap! programs read and write files on the local filesystem via a Node.js middleware server.

Latest version **1.4.0** (published 2026-09-23) · AGPL-3.0-or-later license · 0 weekly downloads

## Install

```sh
npm install @snap-fileio/extension
pnpm add @snap-fileio/extension
yarn add @snap-fileio/extension
bun add @snap-fileio/extension
```

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 1.4.0 |
| Published | 2026-09-23 |
| First published | 2026-03-24 |
| Weekly downloads | 0 |
| License | AGPL-3.0-or-later |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 83.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | craftbrewer |
| Keywords | snap, scratch, fileio, extension, visual-programming, education |

## Links

- npm: https://www.npmjs.com/package/@snap-fileio/extension
- Repository: https://gitlab.com/snap-out/snap-fileio
- Homepage: https://gitlab.com/snap-out/snap-fileio/-/tree/main/packages/extension#readme
- Issues: https://gitlab.com/snap-out/snap-fileio/-/issues
- npm.io page: https://npm.io/package/@snap-fileio/extension

## Recent versions

- 1.4.0 (latest) — 2026-09-23
- 1.3.0 — 2026-04-21
- 1.2.0 — 2026-04-03
- 1.1.0 — 2026-03-28
- 1.0.0 — 2026-03-24

## README

# snap-fileio / extension

This is the Snap! File I/O Extension, a loadable JavaScript extension for the [Snap!](https://snap.berkeley.edu/) visual programming environment that enables Snap! programs to read and write files on the local filesystem via a Node.js middleware server.

The extension registers 13 primitives (8 plain-text, 4 structured data, 1 error reporter) and injects a "Files" block category ("Dateien" in German) into the Snap! palette. It communicates with the middleware over HTTP REST, targeting any server that implements the [API contract](../../docs/api-contract.md).

The extension is consumed by [snap-out](https://gitlab.com/snap-out), which provides the Electron shell, Express server, and workspace configuration.


## Blocks

Block text below is quoted verbatim from [`src/blocks.xml`](src/blocks.xml);
treat that file as authoritative if this table ever drifts.

### Commands

| Block | Description |
|---|---|
| `write %'content' to file %'path'` | Create or overwrite a text file |
| `append %'content' to file %'path'` | Append text to a file |
| `delete file %'path'` | Delete a file |
| `create directory %'path'` | Create a directory |
| `write CSV %'data' to file %'path' %'delim'` | Write list-of-lists as CSV; delimiter is an optional expandable input, default `;` |
| `write JSON %'data' to file %'path'` | Write Snap! data as JSON |

### Reporters

| Block | Returns |
|---|---|
| `read file %'path'` | String |
| `read lines of file %'path'` | List of strings |
| `list files in %'path'` | List of entry names |
| `file %'path' exists?` | Boolean |
| `read CSV file %'path' %'delim'` | List of lists; delimiter is an optional expandable input, default auto-detect |
| `read JSON file %'path'` | Snap! data (objects as list-of-pairs) |
| `last file I/O error` | Error message string, or empty |


## Building

The extension is bundled into a single IIFE file for browser loading:

```
npm run build
```

Output: `dist/snap-fileio-extension.js`


## Testing

```
npm test
```


## License

The Snap! File I/O extension is free software. You may redistribute and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/.

---
_Source: https://npm.io/package/@snap-fileio/extension · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._