Best Practices for Developers
Guidelines for SPECS developers: sample projects, project structure, script conventions, AI context, Git setup, credentials, team workflows, and video tutorials.
These guidelines are for anyone building a Lens for SPECS in Lens Studio, alone or in a team. They
cover where to start (sample projects and the specs-devs resources), how to lay out a project and
write its scripts, how to set up Git and keep credentials out of it, and how a team can share one
scene without losing work. Each section stands on its own, so jump to the one you need.
Start a SPECS project from a sample project
Starting your SPECS development with a sample project is the recommended path. The SPECS sample projects show what the APIs and the platform can do, with working examples of the practices on this page.
You can get the sample projects in two places:
- The Lens Studio Home page. Open a sample from the Lens Studio interface to start from a template or an example. See Lens Studio Home Page.
- GitHub. The
specs-devsGitHub organization holds the full set of SPECS development resources (see What thespecs-devsGitHub organization contains).
What the specs-devs GitHub organization contains
The specs-devs GitHub organization has three repositories of
resources for SPECS developers:
| Repository | What it holds | Use it to |
|---|---|---|
samples | Complete Lens Studio projects, each showing a specific API or platform feature. You can learn from them and build on them. | Start a project, or see a feature working. The Samples page lists them all. |
packages | The unpacked versions of packages you usually install from the Asset Library. | Read a package's source. Keep the copy in your project packed (see Keep Asset Library packages packed). |
context | A filtered, lightweight set of resources curated for AI context engineering, including example rule files. | Give an AI coding assistant SPECS context (see Give an AI coding assistant SPECS context). |
Keep Asset Library packages packed
Keep the packages you install from the Asset Library packed, and keep them up to date. Once you
unpack a package, you can no longer pull its updates from the Asset Library. Unpack a package only
when you must change one of its internal components. The unpacked source of the SPECS packages is in
the specs-devs/packages repository if you only need to
read it.
If you must change a component of an unpacked package:
- Duplicate the component's file, and leave the original unchanged.
- Add a
_Modifiedsuffix to the copy's file name, for exampleInteractable_Modified.ts. - Update your imports to reference the modified copy.
- Mark the package folder as modified, so collaborators know it no longer matches the Asset Library version.
Give an AI coding assistant SPECS context
The specs-devs/context repository is a filtered,
lightweight collection of resources curated for AI context engineering. When you put it in the same
workspace as your Lens Studio project, in an AI code editor such as Cursor, the editor indexes it and
your AI coding assistant can use it. Reference those files when you ask your assistant questions
about SPECS development.
Rules are system prompts that you set in your editor to guide the assistant's behavior. In Cursor,
for example, rules are files in a .cursor/rules/ folder in your workspace (see
Rules in the Cursor documentation for the file format). The context
repository has example rule files you can adapt for SPECS development, in its rules/ folder.
For what context Lens Studio already gives an assistant, and how to add your own, see Give Your AI Agent Lens Studio Context.
Organize the Assets folder of a SPECS project
These guidelines keep a Lens Studio project clean, organized, and maintainable. Keep your own work
in a Project/ folder inside the project's Assets/ folder:
Assets/
├── Project/ # Your main contribution folder
│ ├── Scripts/ # TypeScript and JavaScript source files
│ ├── Materials/ # Custom materials
│ ├── Shaders/ # Custom shader code
│ ├── Textures/ # Texture files
│ ├── Images/ # Image assets
│ ├── Prefabs/ # Reusable scene objects
│ ├── Animations/ # Animation files
│ ├── Sound/ # Audio files
│ └── Data/ # JSON configs and data files
├── Render/ # Rendering-related components
│ ├── CameraTexture/
│ ├── EnvironmentMaps/
│ └── [camera layer configs]
└── Examples/ # Standout examples (optional)
Three kinds of content get folders of their own, outside Assets/Project/:
Render/: keep every rendering component together, such as camera textures and environment maps, along with anything that deals with camera layers and rendering. This keeps rendering concerns separate from the Lens's logic.Examples/: use it when you want users of your project to discover something right away. It suits standout examples that show off key features.- Imported assets: give a complex import, such as a Sketchfab model with many dependencies, its own folder with all its related files. An import that bundles its own animations, textures, and other content can live on its own like this.
Name scripts in a project with both TypeScript and JavaScript
If your project's code exists in both TypeScript and JavaScript, add a TS or JS suffix to each
script's file name:
Scripts/
├── MyComponentTS.ts # TypeScript version
├── MyComponentJS.js # JavaScript version
├── HelperTS.ts # TypeScript helper
└── HelperJS.js # JavaScript helper
The suffix shows at a glance which language version you're working with, and prevents confusion when both versions of a script sit in the same folder.
Comment and document Lens Studio scripts
Write comments as single-line comments, for consistency. When a comment needs more explanation, use several single-line comments:
// Keep comments as one-liners for consistency
// If you need more explanation, use multiple single-line comments
Start each script component with a documentation comment that says what the component does, which other components it's connected to, and what it does at each stage of its lifecycle:
- TypeScript
- JavaScript
/**
* PlayerController
*
* Manages player movement and interaction with the game world.
* Connected to: GameManager, InputHandler, PhysicsSystem
*
* Lifecycle: initializes in onAwake, starts tracking in OnStartEvent
*/
@component
export class PlayerController extends BaseScriptComponent {
// Class implementation
}
/**
* PlayerController
*
* Manages player movement and interaction with the game world.
* Connected to: GameManager, InputHandler, PhysicsSystem
*
* Lifecycle: initializes in onAwake, starts tracking in onStart
*/
function onAwake() {
// Initialization logic
}
function onStart() {
// Start logic
}
onAwake();
script.createEvent('OnStartEvent').bind(onStart);
Give script variables descriptive names and types
In a Lens Studio script, give each variable a name that says what it's for, and a type: a type
annotation in TypeScript, a JSDoc @type comment in JavaScript.
- TypeScript
- JavaScript
@component
export class VariableHints extends BaseScriptComponent {
// Good: clear intent and type
private movementSpeed: number = 5.0;
private targetPosition: vec3 = vec3.zero();
private isInteracting: boolean = false;
// Bad: unclear purpose
private speed = 5.0;
private pos = vec3.zero();
private flag = false;
}
// Good: clear intent (descriptive names and a type comment)
/** @type {number} */
let movementSpeed = 5.0;
/** @type {vec3} */
let targetPosition = vec3.zero();
/** @type {boolean} */
let isInteracting = false;
// Bad: unclear purpose
let speed = 5.0;
let pos = vec3.zero();
let flag = false;
Set up every lifecycle event in a script component
Always set up a script component's lifecycle events, onAwake, OnStartEvent, and UpdateEvent,
even when one of them is empty. This sample also logs each stage when its Enable Logs input is
on:
- TypeScript
- JavaScript
@component
export class MyComponent extends BaseScriptComponent {
@input
enableLogs: boolean = true;
onAwake() {
if (this.enableLogs) {
print('[MyComponent] onAwake called');
}
// Initialization logic
this.createEvent('OnStartEvent').bind(() => {
if (this.enableLogs) {
print('[MyComponent] OnStartEvent triggered');
}
// Start logic
});
this.createEvent('UpdateEvent').bind(() => {
// Update logic (can stay empty)
});
}
}
// @input bool enableLogs = true
function onAwake() {
if (script.enableLogs) {
print('[MyComponent] onAwake called');
}
// Initialization logic
script.createEvent('OnStartEvent').bind(function () {
if (script.enableLogs) {
print('[MyComponent] OnStartEvent triggered');
}
// Start logic
});
script.createEvent('UpdateEvent').bind(function () {
// Update logic (can stay empty)
});
}
onAwake();
Handle missing inputs and control logging in a script component
Check an input that may be left empty
Lens Studio checks every TypeScript @input for undefined: if an input isn't set in the
Inspector, the Lens throws a run-time error. To let an input stay empty and handle that case
yourself, add @allowUndefined to it (see
AllowUndefined in the TypeScript page), then check
the input and print a clear error message when it's missing:
- TypeScript
- JavaScript
@component
export class TargetCheck extends BaseScriptComponent {
@input
@allowUndefined
targetObject: SceneObject;
onAwake() {
if (!this.targetObject) {
print('[ERROR] TargetCheck: targetObject is not assigned');
return;
}
// Proceed with logic
}
}
// @input SceneObject targetObject
function onAwake() {
if (!script.targetObject) {
print('[ERROR] TargetCheck: targetObject is not assigned');
return;
}
// Proceed with logic
}
onAwake();
Turn logging on and off with inputs
Give each script component a logging switch, so you can turn its logs on and off from the Inspector. This sample has two inputs: Enable Logs turns all logs on or off, and Verbose Logs adds detailed messages:
- TypeScript
- JavaScript
@component
export class LoggingComponent extends BaseScriptComponent {
@input
private enableLogs: boolean = true;
@input
private verboseLogs: boolean = false;
private log(message: string, verbose: boolean = false) {
if (!this.enableLogs) return;
if (verbose && !this.verboseLogs) return;
print(`[LoggingComponent] ${message}`);
}
onAwake() {
this.log('Component initialized');
this.log('Detailed initialization info', true); // Verbose log
}
}
// @input bool enableLogs = true
// @input bool verboseLogs = false
function log(message, verbose) {
if (!script.enableLogs) return;
if (verbose && !script.verboseLogs) return;
print('[LoggingComponent] ' + message);
}
function onAwake() {
log('Component initialized');
log('Detailed initialization info', true); // Verbose log
}
onAwake();
Use const and let, and format your code
In Lens Studio scripts, in TypeScript and in JavaScript, declare variables with const or let,
not var:
// Good
const maxHealth = 100;
let currentHealth = 100;
Avoid:
var maxHealth = 100;
Format your scripts with a code formatter such as Prettier. A formatter keeps spacing and syntax consistent across the project, which makes collaboration easier.
Teach users how to use your SPECS Lens
Show users, inside the Lens, how to use it:
- Add text instructions. Include UI text that explains how to use the Lens: its gestures, interactions, and features. Keep the instructions clear and concise.
- Add 3D hand hints. Use the 3D Hand Hints package to show users which hand gestures the Lens needs, and to display hints for specific interaction patterns. Hand hints are essential for a Lens with custom gestures.
Use UI Kit and Interaction Kit components instead of custom ones
For SPECS UI and interactions, prefer the framework components to your own:
- Use UI Kit components for UI elements.
- Use Interaction Kit components for interactions.
- Follow each framework's own best practices.
Import the framework components from their packages. Use a custom implementation, such as a modified copy of a component, only when you need one:
- TypeScript
- JavaScript
// Good: use framework components
import { RectangleButton } from 'UIKit.lspkg/Scripts/Components/Button/RectangleButton';
import { Interactable } from 'InteractionKit.lspkg/Components/Interaction/Interactable/Interactable';
// Only if necessary: custom implementations
import { CustomButton } from './CustomButton_Modified';
// Good: use framework components
const RectangleButton =
require('UIKit.lspkg/Scripts/Components/Button/RectangleButton').RectangleButton;
const Interactable =
require('InteractionKit.lspkg/Components/Interaction/Interactable/Interactable').Interactable;
// Only if necessary: custom implementations
const CustomButton = require('./CustomButton_Modified').CustomButton;
Document a SPECS project repository
Write a README
Give your project repository a README that covers what the Lens does, its features, how to use it, its technical details, a demo, and credits:
# Project Name
Brief description of what your Lens does.
## Features
- Feature 1
- Feature 2
## How to Use
Step-by-step instructions with screenshots or GIFs.
## Technical Details
- Framework dependencies
- API requirements
- Performance considerations
## Demo

## Credits
List any third-party assets or code used.
Add animated GIFs and technical explanations to make the README engaging and informative.
Credit sources in a LICENSE file
Always credit the sources of third-party assets and code, in the repository's LICENSE file:
This project includes assets from:
- [Asset Name] by [Author] - [License Type]
- [Model Name] from Sketchfab by [Creator]
Set up .gitignore and .gitattributes for a Lens Studio project
Lens Studio writes and maintains a .gitignore and a .gitattributes file for you when you save a
project inside a Git repository. Use those files rather than writing your own from scratch:
- In a terminal, go to your project folder and run
git init. - Save the project in Lens Studio. Lens Studio adds
.gitignoreand.gitattributesto the folder, or updates them. - Make your first commit, including both files.
Each generated file has a section that Lens Studio manages, between # Shipped by Lens Studio
markers. Don't edit that section: Lens Studio overwrites it every time it saves. Put your own
entries above or below it. The managed section of .gitignore ignores these:
Cache/**
PluginsUserPreferences/**
Support/**
BackUp/**
Workspaces/**
.vscode/**
/jsconfig.json
/tsconfig.json
.DS_Store
/spk_debug_key.pem
*.lock
It doesn't ignore the Packages/ folder or .lsc files, and you shouldn't either: Packages/
holds the project's installed packages (.lspkg) and custom components (.lsc), so a collaborator
who clones a repository without them gets a project with missing dependencies. Don't commit
spk_debug_key.pem: the managed section already excludes it.
Add your own entries outside the managed section, for example operating system and editor files the managed section doesn't cover, and your credential files (see Keep credentials out of a SPECS project repository):
# Your own entries, above or below the Lens Studio section
Thumbs.db
.idea/
The generated .gitattributes stores everything under Assets/ and Packages/ in Git LFS, and
marks text files such as .js, .json, and .md as text eol=lf so their line endings stay
consistent. Keep it, rather than replacing it with your own line-ending rules: a rule such as
* text=auto drops Git LFS for the project's binary assets. Every collaborator needs Git LFS
installed (git lfs install), or Lens Studio can't open the cloned project. For more on Git and
Lens Studio projects, see
Lens Studio Project Structure.
Keep credentials out of a SPECS project repository
Protecting sensitive information in a Lens Studio project is critical. Never commit tokens, API keys, passwords, or other credentials to a Git repository. Protect these:
- API tokens and keys
- Service account credentials
- Database passwords
- OAuth secrets
- Private encryption keys
Snap Cloud credentials
When you work with Snap Cloud, Import Credentials in the Supabase panel (Window › Supabase)
creates a Supabase Project asset in your project, Assets/SupabaseProject_<ref>.supabaseProject,
which holds your Snap Cloud project's URL and public token. Don't push this asset to Git: add it to
your .gitignore, outside the Lens Studio section:
# Snap Cloud project credentials
*.supabaseProject
Each collaborator then imports the credentials into their own copy of the project. See Lens Setup Guide.
Remote Service Gateway tokens
The Remote Service Gateway uses Snap, OpenAI, and Google tokens tied to your Snapchat account, which
you generate with the Remote Service Gateway Token plugin and enter in the
RemoteServiceGatewayCredentials component. Don't commit a scene where those tokens are visible in
the Inspector:
- Clear the token fields of the
RemoteServiceGatewayCredentialscomponent. - Commit your changes.
- Enter the tokens again locally, for testing.
Alternatively, store the tokens in a separate configuration file that .gitignore excludes, and load
them at run time instead of saving them in the scene. See
Remote Service Gateway.
Keep server-side keys in Edge Function secrets
Keep server-side keys in Snap Cloud Edge Function secrets, not in the Lens: you set them with
supabase secrets set, and the Edge Function reads them as environment variables (see
Edge Functions).
Share any other credentials only through private channels:
- Share credentials only through secure channels, such as encrypted messages and password managers.
- Never share credentials in public forums, Discord, or GitHub issues.
- Rotate a credential immediately if it's accidentally exposed.
Separate development and production configuration files
Create separate configuration files for development and production, and commit only a template without real values:
Assets/
├── Config/
│ ├── development.json # Local dev credentials (gitignored)
│ ├── production.json # Prod credentials (gitignored)
│ └── config.template.json # Template without actual values (committed)
Share a Lens Studio scene in a team with a Scene Master
Lens Studio's project format is designed to keep Git merge conflicts to a minimum, and the Git merge tools Lens Studio sets up reduce them to the essential ones: two people can change different properties of the same object in parallel. A conflict still happens when two people change the same property, or reorder the same part of the scene hierarchy, and scene files are where the whole team's work meets, so their conflicts are the hardest to merge. To avoid them, designate a Scene Master:
- One team member is responsible for the final changes to the scene.
- The other team members work on prefabs and assets.
- The Scene Master integrates the prefabs into the main scene.
For example:
Team Member A → Works on UI prefabs
Team Member B → Works on game logic scripts
Team Member C → Works on visual assets
Scene Master → Integrates all prefabs into main scene
Build the Lens from prefabs
Keep each team member's work modular and reusable by building it as prefabs:
Assets/
├── Project/
│ ├── Prefabs/
│ │ ├── UI/ # UI components by Team Member A
│ │ ├── Gameplay/ # Game objects by Team Member B
│ │ └── Effects/ # VFX by Team Member C
│ └── Scripts/ # Scripts by all team members
Prefab-driven development has these benefits:
- Team members can work on their prefabs independently.
- Prefabs are easier to merge than scene files.
- Changes stay isolated and testable.
- The Scene Master can integrate prefabs without conflicts.
Give each team member a folder
Give each team member's work its own folder in the Assets/Project/ folder:
Assets/
├── Project/
│ ├── TeamMemberA/ # Alice's workspace
│ ├── TeamMemberB/ # Bob's workspace
│ ├── Shared/ # Shared resources
│ └── Integration/ # Scene Master's integration work
This structure minimizes conflicts and makes it clear who owns what.
Commit only the files you changed in a Lens Studio project
Don't stage everything with git add . (add all):
git add .
git commit -m "Updated stuff"
Review your changes and stage the files you edited by name instead:
# Review what changed
git status
# Add specific files you edited
git add Assets/Project/Scripts/PlayerController.ts
git add Assets/Project/Prefabs/UI/MainMenu.prefab
# Verify what's staged
git diff --staged
# Commit with a clear message
git commit -m "Add player movement controls to PlayerController"
Selective commits matter because they:
- Prevent you from committing credentials by accident.
- Keep temporary files and test assets out of the repository.
- Keep the commit history clean and reviewable.
- Make it easier to revert a specific change.
Checklist for a SPECS project
Starting a new project
- Create the
Assets/Project/folder structure. - Set up the
Render/folder for rendering components. - Add a README.md with a project overview.
- Commit the
.gitignoreand.gitattributesthat Lens Studio generates, with your credential files added to.gitignore. - Set up logging with an on/off input.
- If you work in a team, designate a Scene Master.
Writing script components
- Add a class-level documentation comment.
- Set up every lifecycle event, even if empty.
- Add logging with an enable/disable input.
- Handle inputs that may be missing, with error messages.
- Use
constandletinstead ofvar. - Give variables types.
Using packages
- Keep packages packed unless you need to modify them.
- If you modify a component, duplicate it and add a
_Modifiedsuffix. - Update imports to point at the modified components.
Security and Git
- Never commit credentials, tokens, or API keys.
- Add sensitive files to
.gitignore. - Remove credentials from the Inspector before you commit.
- Use
git add <file>instead ofgit add .. - Review changes with
git statusandgit diff.
Before publishing
- Add UI text instructions for users.
- Include 3D hand hints if the Lens uses custom gestures.
- Create an animated GIF for the README.
- Document the technical requirements.
- Credit all third-party assets in LICENSE.
- Run a code formatter (Prettier).
- Verify that no credentials are in the repository.
- Test all features and interactions.
Video tutorials for SPECS development
These videos are recommended viewing for SPECS development:
| # | Video | What it covers |
|---|---|---|
| 1 | Introduction to Lens Studio | Lens Studio basics and an overview of the interface |
| 2 | Building Your First Lens | Building a first SPECS Lens |
| 3 | Connected Lenses | Connected Lenses on SPECS |
| 4 | UI Kit Walkthrough | A walkthrough of UI Kit |
| 5 | Snap ML | The SnapML pipeline for SPECS |
| 6 | Snap Cloud | Getting started with Snap Cloud |
For more tutorials and updates, visit the SPECS developers YouTube channel.
Related
- Samples: every SPECS sample project, to start from.
- Lens Studio Project Structure: what each project file is, and more on Git and Git LFS.
- Give Your AI Agent Lens Studio Context: set up context and rules for an AI coding assistant.
- TypeScript: the decorators used in these samples, such as
@inputand@allowUndefined. - Prefabs: build the reusable pieces a Scene Master integrates.