Hospede seu próprio Playground

Você pode hospedar o Playground no seu próprio domínio ao invés de playground.wordpress.net.

Isso é útil para ter controle total sobre seu conteúdo e comportamento, assim como remover a dependência de um servidor de terceiros. Pode fornecer uma experiência de usuário mais personalizada, por exemplo: um playground com plugins e temas pré-instalados, configurações padrão do site ou conteúdo de demonstração.

Antes de começar

Hospedar o Playground por conta própria dá controle total, mas requer entender alguns conceitos-chave:

O que esperar

Complexidade de configuração inicial: Construir e implantar o Playground envolve múltiplas etapas. Reserve tempo para solução de problemas durante sua primeira implantação.
Hospedagem de arquivos estáticos: O Playground é principalmente arquivos estáticos (HTML, JS, WASM) com requisitos mínimos do lado do servidor.
Execução baseada em navegador: Todo o processamento do WordPress acontece no navegador do usuário via WebAssembly—seu servidor apenas entrega arquivos.

Considerações de desempenho

Os tempos de carregamento dependem de vários fatores:

Fator	Impacto	Otimização
Tamanho do plugin	Plugins grandes (ex. WooCommerce) podem levar 30-60 seg para instalar	Pré-instale plugins no seu build do WordPress
Velocidade da rede	Arquivos WASM têm ~15-30MB	Use CDN com headers de cache apropriados
Navegador	Chrome/Edge têm melhor desempenho; Safari usa mecanismos de fallback	Teste em diferentes navegadores
Dispositivo	Dispositivos móveis carregam mais devagar que desktop	Avise usuários móveis sobre tempos de carga maiores

Compatibilidade com navegadores

O Playground funciona em navegadores modernos, mas com algumas diferenças:

Navegador	Status	Notas
Chrome/Edge	✅ Melhor desempenho	Suporte completo para todas as funcionalidades
Firefox	✅ Bom	Desempenho confiável
Safari	✅ Bom	Melhorias recentes aumentaram significativamente a confiabilidade
Navegadores móveis	⚠️ Limitado	Funciona, mas com maior uso de memória, e uma conexão 4G pode impactar a experiência

Nota técnica: O Safari usa MessagePorts ao invés de SharedArrayBuffer para respostas em streaming. Este mecanismo de fallback funciona de forma confiável mas adiciona uma pequena sobrecarga comparado ao Chrome/Edge.

Uso

Um Playground auto-hospedado pode ser incorporado como um iframe.

<iframe src="https://my-playground.com"></iframe>

Ou carregado dinamicamente passando a URL remota para o Cliente Playground.

import { startPlaygroundWeb } from '@wp-playground/client';

const client = await startPlaygroundWeb({
	iframe: document.getElementById('wp'),
	remoteUrl: `https://my-playground.com/remote.html`,
});

Recursos estáticos

Existem várias maneiras de obter os recursos estáticos necessários para hospedar o Playground.

Em ordem de conveniência e facilidade:

Baixar pacote pré-construído
Fazer fork do repositório e construir com GitHub Action
Construir localmente

Baixar pacote pré-construído

Para hospedar o Playground como está, sem fazer alterações, você pode baixar o artefato construído da última GitHub Action bem-sucedida.

Clique em Deploy Playground website.
Na seção Artifacts no final da página, clique em playground-website.
É um pacote zip com os mesmos arquivos implantados no site público.

Fazer fork do repositório e construir com GitHub Action

Para personalizar o Playground, você pode fazer fork do repositório Git.

Construa-o da página GitHub do seu fork indo para: Actions -> Deploy Playground website -> Run workflow.

Construir localmente

O método mais flexível e personalizável é construir o site localmente.

Crie um clone superficial do repositório do Playground, ou do seu próprio fork.

git clone -b trunk --single-branch --depth 1 --recurse-submodules https://github.com/WordPress/wordpress-playground.git

Entre no diretório wordpress-playground.

cd wordpress-playground

Instale as dependências e construa o site.

npm install
npm run build:website

Este comando internamente executa a tarefa nx build:wasm-wordpress-net. Ele copia os recursos construídos dos pacotes remote e website para uma nova pasta no seguinte caminho:

dist/packages/playground/wasm-wordpress-net

O serviço completo do Playground consiste no conteúdo desta pasta.

Resumo dos arquivos incluídos

Os recursos estáticos incluem:

Arquivos de dados e WASM para todas as versões disponíveis de PHP e WordPress
remote.html - o núcleo do Playground
index.html - o shell, ou chrome do navegador
Script Web Worker

Você pode implantar o conteúdo da pasta no seu servidor usando SSH, como scp ou rsync.

É um site estático, exceto por estes aspectos dinâmicos.

Arquivo de diretiva do servidor Apache .htaccess do pacote remote

Para que estes funcionem, você precisa de um ambiente de servidor com Apache e PHP instalados.

Configuração NGINX

Como alternativa ao Apache, aqui está um exemplo de uso do NGINX para servir o Playground.

Consulte o arquivo fonte

O exemplo pode estar desatualizado. Por favor verifique o arquivo fonte para a versão mais recente.

O arquivo Apache .htaccess combinado se parece com isso.

AddType application/wasm .wasm

Um equivalente em NGINX.

location ~* .wasm$ {
  types {
    application/wasm wasm;
  }
}

Você pode precisar ajustar o acima de acordo com as especificidades do servidor, particularmente como invocar PHP para o caminho /plugin-proxy.

O servidor web Caddy não requer nenhuma configuração especial para funcionar.

Personalizar dados empacotados

O arquivo wp.zip é um pacote de todos os arquivos para o sistema de arquivos virtual no Playground. Há um arquivo de dados para cada versão disponível do WordPress.

O pacote em packages/playground/wordpress-builds é responsável por construir estes arquivos de dados.

Edite o script de construção no Dockerfile para criar um pacote personalizado que inclui plugins pré-instalados ou conteúdo.

Para reconstruir os builds do WordPress após personalizar o Dockerfile, execute o seguinte comando:

npm run rebuild:wordpress-builds

Para reconstruir o site para incluir os builds personalizados do WordPress, siga as instruções aqui.

Instalar plugins

Aqui está um exemplo de instalação de plugins para o pacote de dados.

Antes da seção intitulada Strip whitespaces from PHP files.

# === Preinstall plugins ===

RUN cd wordpress/wp-content/mu-plugins && \
    # Install plugins
    for plugin_name in example-plugin-1 example-plugin-2; do \
      curl -L https://downloads.wordpress.org/plugin/{$plugin_name}.latest-stable.zip -o {$plugin_name}.zip && \
      unzip $plugin_file && \
      rm $plugin_file && \
      # Create entry file in mu-plugins root
      echo "<?php require_once __DIR__.'/$plugin_name/$plugin_name.php';" > $plugin_name.php; \
    done;

Você pode baixar plugins de URLs diferentes do diretório de plugins do WordPress, ou usar Git para obtê-los de outro lugar.

Também é possível copiar de uma pasta local. Por exemplo, antes de RUN:

COPY ./build-assets/*.zip /root/

Então coloque os arquivos zip dos plugins em build-assets. Neste caso, você pode querer adicionar seus caminhos ao .gitignore.

Importar conteúdo

Aqui está um exemplo de importação de conteúdo.

# === Demo content ===

COPY ./build-assets/content.xml /root/
RUN cd wordpress ; \
     echo "Importing content.."; \
    ../wp-cli.phar --allow-root import /root/content.xml --authors=create

Isso assume que você colocou um arquivo de exportação WXR chamado content.xml na pasta build-assets. Você pode adicionar seu caminho ao .gitignore.

Lista de verificação para implantação em produção

Antes de ir para produção, verifique se seu Playground auto-hospedado atende a estes requisitos:

Configuração do servidor

Tipos MIME: Garanta que arquivos .wasm sejam servidos com tipo de conteúdo application/wasm
Headers CORS: Se incorporar cross-origin, configure headers CORS apropriados
Cache: Defina tempos de cache longos para WASM e recursos estáticos (eles são versionados)
Compressão: Habilite gzip/brotli para transferências de arquivos mais rápidas
HTTPS: Necessário para service workers e algumas funcionalidades do navegador

Otimização de desempenho

CDN: Sirva recursos estáticos de um CDN para entrega global mais rápida
Plugins pré-instalados: Empacote plugins frequentemente usados no seu build do WordPress
Blueprints mínimos: Mantenha instalações de plugins em tempo de execução no mínimo

Solução de problemas

Problemas comuns e soluções

Playground não carrega ou mostra tela em branco

Possíveis causas:

Servidor não serve arquivos WASM com tipo MIME correto
Implantação faltando arquivos necessários
Erros JavaScript no console do navegador

Soluções:

Verifique o console do navegador para erros (F12 → aba Console)
Verifique se arquivos .wasm retornam tipo de conteúdo application/wasm
Verifique se você implantou todos os arquivos de construção

Carregamento inicial lento (30+ segundos)

Possíveis causas:

Instalando plugins grandes em tempo de execução
Faltando configuração de CDN ou cache
Usuário em conexão de rede lenta

Soluções:

Pré-instale plugins no seu build do WordPress ao invés de instalação em tempo de execução
Configure CDN com headers de cache apropriados
Mostre indicadores de carregamento para definir expectativas do usuário

Antes de começar​

O que esperar​

Considerações de desempenho​

Compatibilidade com navegadores​

Uso​

Recursos estáticos​

Baixar pacote pré-construído​

Fazer fork do repositório e construir com GitHub Action​

Construir localmente​

Resumo dos arquivos incluídos​

Configuração NGINX​

Personalizar dados empacotados​

Instalar plugins​

Importar conteúdo​

Lista de verificação para implantação em produção​

Configuração do servidor​

Otimização de desempenho​

Solução de problemas​

Problemas comuns e soluções​

Playground não carrega ou mostra tela em branco​

Carregamento inicial lento (30+ segundos)​