# iframe-sandbox

> creates a sandboxed iframe with methods for eval and writing to document body

Latest version **4.0.1** (published 2015-06-27) · ISC license · 0 weekly downloads

## Install

```sh
npm install iframe-sandbox
pnpm add iframe-sandbox
yarn add iframe-sandbox
bun add iframe-sandbox
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

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

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.0.1 |
| Published | 2015-06-27 |
| First published | 2015-02-25 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 6 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Maintainers | kumavis |

## Links

- npm: https://www.npmjs.com/package/iframe-sandbox
- Repository: https://github.com/kumavis/iframe-sandbox
- Homepage: https://github.com/kumavis/iframe-sandbox#readme
- Issues: https://github.com/kumavis/iframe-sandbox/issues
- npm.io page: https://npm.io/package/iframe-sandbox

## Dependencies (6)

- [dnode](https://npm.io/package/dnode.md) ^1.2.0
- [xtend](https://npm.io/package/xtend.md) ^4.0.0
- [iframe](https://npm.io/package/iframe.md) ^0.3.1
- [meowserify](https://npm.io/package/meowserify.md) ^1.0.0
- [fifo-transform](https://npm.io/package/fifo-transform.md) ^1.0.2
- [readable-stream](https://npm.io/package/readable-stream.md) ^2.0.0

## Recent versions

- 4.0.1 (latest) — 2015-06-27
- 4.0.0 — 2015-05-02
- 3.1.2 — 2015-05-02
- 3.1.1 — 2015-05-01
- 3.1.0 — 2015-04-13
- 3.0.1 — 2015-03-30
- 3.0.0 — 2015-03-30
- 2.1.0 — 2015-03-25
- 2.0.4 — 2015-03-25
- 2.0.2 — 2015-03-20
- 2.0.1 — 2015-03-20
- 2.0.0 — 2015-03-20
- 1.0.2 — 2015-02-26
- 1.0.1 — 2015-02-25
- 1.0.0 — 2015-02-25

## README

### Iframe Sandbox

Don't assume this is a perfect sandbox.
Infinite loops will crash the main page.
See [this thread](http://stackoverflow.com/questions/11510483/will-a-browser-give-an-iframe-a-separate-thread-for-javascript).

### usage

```js
var IframeSandbox = require('iframe-sandbox')

IframeSandbox({ container: document.body }, function(err, sandbox){

  console.log('ready')

  sandbox.eval('1+2', function(err, result){
    console.log('eval:',result)
  })

})
```

### config

All config options are passed to [`iframe`](https://github.com/npm-dom/iframe).
See here for [`iframe` config options](https://github.com/npm-dom/iframe#options).

```js
var opts = {
  container: document.body,  
  src: urlOfBootstrappedIframe,  
}

IframeSandbox(opts, cb)
```

###### Bootstrapped iframe

To use a hosted, bootstrapped iframe, specify the url as the `src` config option.
See [here](https://github.com/kumavis/iframe-sandbox-bootstrap) for more about using a bootstrapped iframe.


### methods

###### eval

Evals js in the sandbox's context.
Calls the callback with the error (as a string) or the result.

```js
sandbox.eval( jsString, function(err, result){ /* ... */ } )
```

###### createWriteStream

Creates a WriteStream that writes to the document via `document.write`.
Note: scripts written to the DOM wont be run until 'document.close()' is called,
triggered by the end of the stream.

```js
var ws = sandbox.createWriteStream()
somewhereAwesome.pipe(ws)
```

###### 'message' event

Inside the sandbox context there is an extra exposed global `sandboxMessage` that will re-materialize objects in the main context and handle cross-context callbacks via [dnode](https://github.com/substack/dnode).
Listen to the 'message' event in the main context to receive the messages

```js
sandbox.on('message', function(arg1, arg2, ...){
  console.log(arguments)
})

sandbox.eval('sandboxMessage("hello", "world")')
```

### notes

Writing external script tags to the document does not seem to work.
The following will not load `bundle.js`.
```js
var ws = sandbox.createWriteStream()
ws.write('<script src="bundle.js"></script>')
ws.end()
```

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