Skip to content

Commit

Permalink
Merge pull request #202 from codesandbox/docs/custom-content
Browse files Browse the repository at this point in the history 
docs: custom content rewrite
  • Loading branch information
@sannek
sannek authored Nov 30, 2021
2 parents 32c0818 + 944db66 commit fa9e827
Showing 1 changed file with 65 additions and 106 deletions.
171 changes: 65 additions & 106 deletions website/docs/docs/getting-started/custom-content.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,15 @@ import { NestedSandpack } from "../../src/NestedSandpack";

# Custom Content

The `Sandpack` component that you used in the previous section is called a `preset`. It wraps all the individual components and provides some smart defaults.
The `Sandpack` component you used in the precious section is called a `preset`. It wraps the all the individual components and provides sensible defaults.

Presets were designed to ease the adoption of `sandpack`, while offering extensive configurability. The first thing we are looking at is how to configure the content that runs inside `sandpack`.
Presets make it easy to adopt `sandpack`, while offering extensive configurability. The first thing we will look at is how to configure the content that runs inside `sandpack`.

## Template
## Templates

Your `Sandpack` instance can start with a predefined `template`. A template is a
collection of `files` and `dependencies`, a basic starter for a sandbox, if you want.
The `vue` template in this instance, has the starter files generated by the `vue-cli`.
By default your `Sandpack` instance starts with a predefined `template`.
Each template contains all the `files` and `dependencies` needed to start a project. For instance, the `vue`
template will contain the starter files generated by the `vue-cli`, and the `react` template those generated by `create-react-app`.

<!-- prettier-ignore -->
<NestedSandpack nestedProps={` // Try out the included templates below!
Expand All @@ -27,14 +27,11 @@ The `vue` template in this instance, has the starter files generated by the `vue
// template="vanilla" // default`}
/>

The template prop accepts a string and has the following valid options: `react`, `react-ts`, `vue`, `vue3`, `angular`, `vanilla`, and `vanilla-ts`. If the template prop is invalid, it default to `vanilla`.
The template prop accepts a string, and has a variety of presets. The complete list of included templates might change over time, so check the [API reference](https://sandpack.codesandbox.io/docs/api/react/components/#sandpackpredefinedtemplate) for the supported templates. If the template prop is not passed or has an invalid value, it defaults to `vanilla`.

## Files
## Custom File Contents

In most of the cases, you will want to pass custom code to the sandpack
instance. For this, you can use the `files` prop.

The code is passed as a `string` and should be pre-formatted:
Once you've chosen your starter template, you will most likely want to pass custom code into your `Sandpack` instance. The simplest way to do this, is to add and override files via the `files` prop.

<!-- prettier-ignore -->
<NestedSandpack
Expand All @@ -48,18 +45,59 @@ const code = \`export default function App() {
}}`}
/>

The `files` prop accepts an object, where each `key` is the **relative path** of the file in the sandbox folder
structure. Files are added on top of the `template` structure. Furthermore, the `template` is using the same type to [define the files](https://github.com/codesandbox/sandpack/blob/main/sandpack-react/src/templates/react.ts) it contains. With this in mind, you can overwrite any of the template/sandbox
files (eg: `/index.js`, `/index.css`, etc.)
The `files` prop accepts an object, where each `key` is the **relative path** of that file in the sandbox folder structure. Files passed in through the `files` prop override those in the `template` structure. Since each `template` uses the same type to define the files, you can overwrite the contents of any of the template files.

Keep in mind that the tabs only show the name of the file and not the full path. For instance, if you want to overwrite `/index.js` in the `vanilla` template, you need to specify `/src/index.js` as the corresponding `key` in the `files` object. You can check the full paths for each of the templates in the [template definitions](https://github.com/codesandbox/sandpack/tree/main/sandpack-react/src/templates)

:::note Leading slash
Make sure you don't omit the leading slash (`/`) when setting the file paths
:::note Leading Slash
Don't forget the leading slash (`/`) when setting the file paths.
:::

:::info Available files
Notice that when passing the `files` prop, only the content you pass there is available in the file tabs. The other files are still bundled together, but you don't see them.
:::info Available Files
Notice that when passing the `files` prop, only the content you pass there is available in the file tabs. The other files in the template are still bundled together, but you don't see them anymore.
:::

## Dependencies

Any `template` will include the needed dependencies, but you can specify any additional dependencies.

### NPM Dependencies

Inside `customSetup` prop you can pass a `dependencies` object. The `key` should be the name of the package, while the value is the `version`, in exactly the same format as it would be inside `package.json`.

```jsx
<Sandpack
template="react"
files={{
"/App.js": `...`,
}}
customSetup={{
dependencies: {
react: "17.0.2",
"react-dom": "17.0.2",
"react-scripts": "4.0.0",
},
}}
/>
```

### Static External Resources

You can also pass an array of `externalResources` into the `options` prop to specify static links to external CSS or JS resources elsewhere on the web. These resources get injected into the `head` of your HTML and are then globally available.

```jsx
<Sandpack
options={{
'externalResources': [
"https://unpkg.com/@tailwindcss/ui/dist/tailwind-ui.min.css"
]
}}
template="react"
/>
```

## Advanced Usage

### Hidden Files

Sometimes you might want to pass some custom code to `Sandpack`, but you don't want the users to see that code. For example, you might have some stylesheet that should not be editable but helps you in your examples.
Expand Down Expand Up @@ -111,43 +149,15 @@ default:
```

:::info
The `active` flag has precendence over the `hidden` flag. So a file with both of these set as `true` will be visible.
The `active` flag has precendence over the `hidden` flag. So a file with both `hidden` and `active` set as `true` will be visible.
:::

### Links on external resources

You can also use `externalResources` property to specify the static links on external resources such as CSS files or images presence somewhere in the web:

```jsx
<Sandpack
files={{
'/App.js': reactCode,
'/button.js': {
code: buttonCode,
active: true,
}
'/link.js': {
code: linkCode,
hidden: true,
},
}}
options={{
'externalResources': [
"https://unpkg.com/@tailwindcss/ui/dist/tailwind-ui.min.css"
]
}}
template="react"
/>
```

### openPaths and activePath

You can override the entire hidden/active system with two settings (`openPaths` and `activePath`) inside the
`options` prop.
`options` prop.

The `options` prop contains a lot of other configuration fields we will talk about later.

Notice that both options require you to match the file paths inside the sandbox, so use this with caution as it can generate errors on the long term.
Notice that both options require you to match the exact file paths inside the sandbox, so use with caution as this can quite easily create errors in the long term.

```jsx
<Sandpack
Expand All @@ -168,58 +178,7 @@ When `openPaths` or `activePath` are set, the `hidden` and `active` flags on the
`files` prop are ignored.
:::

## Custom Setup

With the `customSetup` prop you have the flexibility to adjust or extend the details of `template` prop. Also the `customSetup` prop can be used to configure **dependencies**.

```jsx
const code = `import ReactMarkdown from 'react-markdown'
export default function App() {
return <ReactMarkdown># Hello, *CodeSandbox*!</ReactMarkdown>
}`;

<Sandpack
template="react"
files={{
"/App.js": code,
}}
customSetup={{
dependencies: {
"react-markdown": "latest",
},
}}
/>;
```

TODO: Inject example

If both `template` and
`customSetup` are provided, the two are merged, with the `customSetup` values
having higher priority. If you don't want to start from a template, you can
specify your entire sandbox structure with the `customSetup`.

### Dependencies

Inside `customSetup` you can pass a `dependencies` object. The `key` should be the name of the package, while the value is the `version`, exactly in the same format as you would pass it inside `package.json`.

```jsx
<Sandpack
template="react"
files={{
"/App.js": `...`,
}}
customSetup={{
dependencies: {
react: "17.0.2",
"react-dom": "17.0.2",
"react-scripts": "4.0.0",
},
}}
/>
```

### Entry File
### Custom Entry File

Additionally, you can also specify a different `entry` file for the sandbox. The entry file is the starting point of the bundle process.

Expand All @@ -239,8 +198,8 @@ Additionally, you can also specify a different `entry` file for the sandbox. The
If you change the path of the entry file, make sure you control all the files that go into the bundle process, as prexisting settings in the `template` might not work anymore.
:::

---
### Fully Custom Setup

:::success Congrats!
You learned the basics of configuring content that goes inside a `Sandpack` instance. The next section will guide you though UI customization.
:::
Sometimes you might not want to start from any of the preset templates. If so, you can pass a full `customSetup` object that contains everything needed for your custom `Sandpack` configuration.

Most individual parts of the `customSetup` have been described above, but for a full overview of what is accepted in a custom setup, check out the [type definitions](https://github.com/codesandbox/sandpack/blob/main/sandpack-react/src/types.ts)

0 comments on commit fa9e827

Please sign in to comment.