From 7076425dd5f7ea8e52c2e56ba91c69e1c97e70e7 Mon Sep 17 00:00:00 2001 From: Sanne Date: Mon, 29 Nov 2021 17:21:01 +0000 Subject: [PATCH 1/3] wip: custom content update --- .../getting-started/custom-content-new.md | 232 ++++++++++++++++++ 1 file changed, 232 insertions(+) create mode 100644 website/docs/docs/getting-started/custom-content-new.md diff --git a/website/docs/docs/getting-started/custom-content-new.md b/website/docs/docs/getting-started/custom-content-new.md new file mode 100644 index 000000000..8172c1020 --- /dev/null +++ b/website/docs/docs/getting-started/custom-content-new.md @@ -0,0 +1,232 @@ +--- +sidebar_position: 3 +--- + +import { NestedSandpack } from "../../src/NestedSandpack"; + +# Custom Content + +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 make it easy to adopt `sandpack`, while offering extensive configurability. The first thing we'll look at is how to configure the content that runs inside `sandpack`. + +## Templates + +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`. + + + + +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 not passed or has an invalid value, it defaults to `vanilla`. + +## Custom File Contents + +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. + + +Hello Sandpack +}\`;`} + nestedProps={` template="react" + files={{ + "/App.js": code, + }}`} + /> + +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 +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 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` 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 + +``` + +### Static External Resources + +You can also use the `externalResources` option to specify the static links on external resources such as CSS files or images present somewhere in the web: + +```jsx + +``` + +## Advanced Usage + +### Hidden Files + +### 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. + +Instead of passing a `string` as the value of each `file` in the `files` prop, you can pass an object. With this format the content is passed as the `code` property and you can pass additional flags +to customize the sandpack experience. For example, you can pass a `hidden` flag for files that you don't want to show to the user: + +```jsx + +``` + +The `hidden` flag is `false` by default. + +:::info +You can use the object notation only for the files which need additional flags, while the other files can be passed as a `string`. +::: + +### Active File + +You can also specify the `active` file, which is open in the code editor +when the component mounts. If no `active` flag is set, the first file will be active by +default: + +```jsx + +``` + +:::info +The `active` flag has precendence over the `hidden` flag. So a file with both of these 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 + +``` + +### openPaths and activePath + +You can override the entire hidden/active system with two settings (`openPaths` and `activePath`) inside the +`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. + +```jsx + +``` + +:::info +When `openPaths` or `activePath` are set, the `hidden` and `active` flags on the +`files` prop are ignored. +::: + +### 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. + +```jsx + +``` + +:::warning +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 + +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. + +The 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) \ No newline at end of file From 692be88af94c08e0ab8649d0b72bcbf913e9402f Mon Sep 17 00:00:00 2001 From: Sanne Date: Tue, 30 Nov 2021 10:47:35 +0000 Subject: [PATCH 2/3] custom content rewrite --- .../getting-started/custom-content-new.md | 232 ------------------ .../docs/getting-started/custom-content.md | 167 +++++-------- 2 files changed, 63 insertions(+), 336 deletions(-) delete mode 100644 website/docs/docs/getting-started/custom-content-new.md diff --git a/website/docs/docs/getting-started/custom-content-new.md b/website/docs/docs/getting-started/custom-content-new.md deleted file mode 100644 index 8172c1020..000000000 --- a/website/docs/docs/getting-started/custom-content-new.md +++ /dev/null @@ -1,232 +0,0 @@ ---- -sidebar_position: 3 ---- - -import { NestedSandpack } from "../../src/NestedSandpack"; - -# Custom Content - -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 make it easy to adopt `sandpack`, while offering extensive configurability. The first thing we'll look at is how to configure the content that runs inside `sandpack`. - -## Templates - -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`. - - - - -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 not passed or has an invalid value, it defaults to `vanilla`. - -## Custom File Contents - -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. - - -Hello Sandpack -}\`;`} - nestedProps={` template="react" - files={{ - "/App.js": code, - }}`} - /> - -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 -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 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` 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 - -``` - -### Static External Resources - -You can also use the `externalResources` option to specify the static links on external resources such as CSS files or images present somewhere in the web: - -```jsx - -``` - -## Advanced Usage - -### Hidden Files - -### 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. - -Instead of passing a `string` as the value of each `file` in the `files` prop, you can pass an object. With this format the content is passed as the `code` property and you can pass additional flags -to customize the sandpack experience. For example, you can pass a `hidden` flag for files that you don't want to show to the user: - -```jsx - -``` - -The `hidden` flag is `false` by default. - -:::info -You can use the object notation only for the files which need additional flags, while the other files can be passed as a `string`. -::: - -### Active File - -You can also specify the `active` file, which is open in the code editor -when the component mounts. If no `active` flag is set, the first file will be active by -default: - -```jsx - -``` - -:::info -The `active` flag has precendence over the `hidden` flag. So a file with both of these 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 - -``` - -### openPaths and activePath - -You can override the entire hidden/active system with two settings (`openPaths` and `activePath`) inside the -`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. - -```jsx - -``` - -:::info -When `openPaths` or `activePath` are set, the `hidden` and `active` flags on the -`files` prop are ignored. -::: - -### 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. - -```jsx - -``` - -:::warning -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 - -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. - -The 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) \ No newline at end of file diff --git a/website/docs/docs/getting-started/custom-content.md b/website/docs/docs/getting-started/custom-content.md index aaa1217c5..54ef8bea0 100644 --- a/website/docs/docs/getting-started/custom-content.md +++ b/website/docs/docs/getting-started/custom-content.md @@ -6,15 +6,13 @@ 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 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`. -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 the following valid options: `react`, `react-ts`, `vue`, `vue3`, `angular`, `vanilla`, and `vanilla-ts`. 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. -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 + +``` + +### 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 + +``` + +## 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. @@ -111,43 +147,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 - -``` - ### openPaths and activePath You can override the entire hidden/active system with two settings (`openPaths` and `activePath`) inside the -`options` prop. - -The `options` prop contains a lot of other configuration fields we will talk about later. +`options` prop. -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 # Hello, *CodeSandbox*! -}`; - -; -``` - -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 - -``` - -### 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. @@ -237,8 +196,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) \ No newline at end of file From 944db66503c26b2a068348a9c67e6aa615f108ae Mon Sep 17 00:00:00 2001 From: Sanne Date: Tue, 30 Nov 2021 14:03:23 +0000 Subject: [PATCH 3/3] refer to types for list of templates --- website/docs/docs/getting-started/custom-content.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/getting-started/custom-content.md b/website/docs/docs/getting-started/custom-content.md index e3e677972..be132cebb 100644 --- a/website/docs/docs/getting-started/custom-content.md +++ b/website/docs/docs/getting-started/custom-content.md @@ -27,7 +27,7 @@ template will contain the starter files generated by the `vue-cli`, and the `rea // 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 not passed or has an invalid value, it defaults 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`. ## Custom File Contents