# Create samples for your package > Include optional samples that help users learn the package and import example content. You can create samples to include in a Unity Package Manager (UPM) package you develop. Although optional, including samples helps users learn how to use your package. A sample might be a piece of example code, some shaders and textures, some animation, or any other files that you typically find under the project's `Assets` folder. When you open the Package Manager window and select a package containing samples, an **Import** button appears in the package's [details panel](/engine/6000.5/manual/packages-list/upm-ui-window/upm-ui-details.md) for each sample in the package. When you select **Import**, the Package Manager copies the whole subfolder structure for that sample under the project's `Assets` folder. To add samples to your package: 1. Put the asset files or C# code files [under the Samples folder](#sample-subfolder). You can have more than one sample in a package. Each subfolder of the `Samples` folder has one sample. 2. Open the package manifest file (`package.json`) for editing. To locate the file, refer to [Locate the manifest file](/engine/6000.5/manual/packages-list/cus-pkg-lp/cus-pkg-development/cus-pkg-manifest/cus-edit-manifest.md#locate-manifest). 3. If the file doesn't contain a JSON array called `samples`, add it. 4. For each sample you want to include, add a JSON object in the `samples` array. 5. Include the following keys and values for each JSON object in the `samples` array: | **Key** | **Description** | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `displayName` | The name of the sample as it appears in the package details panel of the Package Manager window. | | `description`(optional) | A brief description of what the sample demonstrates or contains. This description appears in the **Samples** tab of the Package Manager window's details panel. | | `path` | The path to the sample’s folder, starting with `Samples`. | | `images`(optional) | An array of strings that specifies image file paths, relative to the package root, starting with the sample folder path specified in `path`. The images appear in the details panel when viewing a sample from the **All Samples** view. | 6. Make sure that `package.json` contains valid JSON. You can check its validity using an online JSON validator or directly in your code editor, if it supports JSON syntax checking. 7. Save the file. ## Images support If you include the `images` array, consider the following when adding images: * The recommended aspect ratio is 16:9, such as 1920 × 1080. * Supported formats are BMP, EXR, HDR, IFF, JPG/JPEG, PICT, PNG, PSD, SVG, TGA, TIFF. * The PNG format is recommended for images with an alpha channel or transparency. ## Location of sample files You can add your sample assets under subfolders of the `Samples` folder of your package. For example, a package with shader samples might look something like this: ```lang-plain MyPackage ├── package.json └── Samples ├── SamplesHDRP │ ├── Images │ | ├── CarouselImage1.png │ | └── CarouselImage2.png │ ├── Shader │ | ├── Lit Texture Blend HDRP.ShaderGraph │ | └── Lit Vertex Color HDRP.ShaderGraph │ └── Textures │ ├── MossyRock.bmp │ └── SandyRock.bmp └── SamplesStandard │ ├── Images │ | ├── CarouselImage1.png │ | └── CarouselImage2.png │ ├── Shader │ | ├── StandardTextureBlend.shader │ | └── StandardVertexColor.shader │ └── Textures │ ├── MossyRock.bmp │ └── SandyRock.bmp └── SamplesUniversalRP ├── Images | ├── CarouselImage1.png | └── CarouselImage2.png ├── Shader | ├── Lit Texture Blend URP.ShaderGraph | └── Lit Vertex Color URP.ShaderGraph └── Textures ├── MossyRock.bmp └── SandyRock.bmp ``` ## Example of a samples array in the manifest file Using the same structure as the example for [Location of sample files](#sample-subfolder), the `samples` array in `package.json` looks similar to this: ```lang-json { "samples": [ { "displayName": "HDRP Shaders", "description": "Contains sample shaders for the High Definition render pipeline", "path": "Samples/SamplesHDRP", "images": ["Samples/SamplesHDRP/Images/CarouselImage1.png", "Samples/SamplesHDRP/Images/CarouselImage2.png"] }, { "displayName": "Standard RP Shaders", "description": "Contains sample shaders for the Standard render pipeline", "path": "Samples/SamplesStandard", "images": ["Samples/SamplesStandard/Images/CarouselImage1.png", "Samples/SamplesStandard/Images/CarouselImage2.png"] }, { "displayName": "URP Shaders", "description": "Contains sample shaders for the Universal render pipeline", "path": "Samples/SamplesUniversalRP", "images": ["Samples/SamplesUniversalRP/Images/CarouselImage1.png", "Samples/SamplesUniversalRP/Images/CarouselImage2.png"] } ] } ``` ## Samples folder naming convention When creating your package with the **Create package** function, keep the samples path in your `package.json` pointing to `Samples`. Don't append a trailing tilde (`~`). During the [export process](/engine/6000.5/manual/packages-list/cus-pkg-lp/cus-pkg-development/cus-export.md), Unity will rename the `Samples` folder to `Samples~` automatically so that it's hidden in the `Packages` folder of the **Project** window. You don't need to adjust the path values for samples in your manifest file. The Package Manager will resolve the sample path correctly. After developers import your sample, they can find it in the `Assets` folder of the **Project** window. ## Additional resources * [Package creation](/engine/6000.5/manual/packages-list/cus-pkg-lp.md) * [Package development workflow](/engine/6000.5/manual/packages-list/cus-pkg-lp/cus-pkg-development/custom-packages.md) * [Edit the package manifest](/engine/6000.5/manual/packages-list/cus-pkg-lp/cus-pkg-development/cus-pkg-manifest/cus-edit-manifest.md) * [Package manifest reference](/engine/6000.5/manual/packages-list/cus-pkg-lp/cus-pkg-development/cus-pkg-manifest/upm-manifest-pkg.md)