GitHub

📚 API

Bundler

Ao invés do cliente, você pode utilizar a API para inicializar o bundler, para casos mais avançados (por exemplo, um processamento customizado após cada build). Um exemplo com toda opção explicada:

const Bundler = require('parcel-bundler');
const Path = require('path');

// Localização do arquivo como único entrypoint:
const entryFiles = Path.join(__dirname, './index.html');
// Ou: múltiplos arquivos como globbing (também pode ser como .js)
// const entryFiles = './src/*.js';
// Ou: múltiplos arquivos em um array
// const entryFiles = ['./src/index.html', './some/other/directory/scripts.js'];

// Opções do bundler
const options = {
  outDir: './dist', // O diretório de saída para construir os arquivos, dist é o padrão
  outFile: 'index.html', // O nome do arquivo de saída
  publicUrl: '/', // A URL onde o servidor será servido, '/' é o padrão
  watch: true, // whether to watch the files and rebuild them on change, defaults to process.env.NODE_ENV !== 'production'
  cache: true, // Habilita ou desabilita o cache, true é o padrão
  cacheDir: '.cache', // O diretório de cache a ser utilizado, .cache é o padrão
  contentHash: false, // Desabilita o hash de conteúdo de ser incluído no nome do arquivo
  global: 'moduleName', // Expor módulos como UMD utilizando este nome, desativado por padrão
  minify: false, // Minifica o arquivo, habilitado se process.env.NODE_ENV === 'production'
  scopeHoist: false, // Torna ligado a flag de scope hoisting/tree shaking experimental, para pequenas builds de produção
  target: 'browser', // browser/node/electron, browser é o padrão
  bundleNodeModules: false, // Por padrão, as dependências do package.json não são incluídas ao usar a opção 'node' ou 'electron' na opção 'target' acima. Defina como true para adicioná-los ao bundle, false é o padrão
  https: { // Define um par costumizado de {chave, certificado}, use true para gerar um ou false para utilizar http.
    cert: './ssl/c.crt', // caminho para um certificado customizado.
    key: './ssl/k.key' // caminho para uma chave customizada
  },
  logLevel: 3, // 5 = irá salvar tudo em um arquivo, 4 = assim como o 3 mas com timestamp e adicionalmente irá logar as requisições http realizadas para o servidor, 3 = irá loggar tudo, 2 = irá loggar avisos e erros, 1 = irá loggar erros
  hmr: true, // Habilita ou desabilita o HMR enquanto "watching" está ativo
  hmrPort: 0, // A porta onde o socket HMR está rodando, o padrão é uma porta livre aleatória (0 no node.js resolve para uma porta livre)
  sourceMaps: true, // Habilita ou desabilita sourcemaps, habilitado é o padrão (builds minificadas atualmente sempre criam sourcemaps)
  hmrHostname: '', // Um hostname para hot module reload, "" é o padrão
  detailedReport: false // Exibe um report detalhado dos bundles, assets, tamanho de arquivos e tempos, false é o padrão, os reports são exibidos somente se o watch estiver desabilidado
};

(async function() {
  // Inicializa o bundler utilizando a localização do entrypoint e as configurações especificadas.
  const bundler = new Bundler(entryFiles, options);

  // Executa o bundler, isto retorna o bundle principal
  // Utiliza os eventos, se você estiver com o modo watch essa promise será disparada uma única vez e não a cada rebuild
  const bundle = await bundler.bundle();
})();

Se você quiser user/iniciar o servidor built-in de desenvolvimento do Parcel, você pode utilizar bundler.serve(). Isso chama bundler.bundle() e inicia um servidor http (ou https) simples. serve() recebe 3 argumentos (todos eles opcionais), o primeiro é a porta, o segundo é https (isto pode ser um objeto {cert, key} apontando para o local da chave e arquivo do certificado ou true para gerar uma chave) e o terceiro é o host.

Eventos

Esta é a lista com todos os eventos do bundler:

const bundler = new Bundler(...);
bundler.on('bundled', (bundle) => {
  // o bundler contém todos os assets e bundles, veja a documentação para mais detalhes.
});
// Chame isto para iniciar o bundling.
bundler.bundle();
const bundler = new Bundler(...);
bundler.on('buildEnd', () => {
  // Faz algo...
});
// Chame isto para iniciar o bundling.
bundler.bundle();
const bundler = new Bundler(...);
bundler.on('buildStart', entryPoints => {
  // Faz algo...
});
// Chame isto para iniciar o bundling.
bundler.bundle();
const bundler = new Bundler(...);
bundler.on('buildError', error => {
  // Faz algo...
});
// Chame isto para iniciar o bundling.
bundler.bundle();

Bundle

Um Bundle é o que o Parcel utiliza para juntar todos os assets juntos, isto contém bundles filhos e irmão para que seja possível contruir a árvore de pacotes.

Propriedades

Árvore

O Bundle contém parentBundle, childBundles e siblingBundles, todas essas propriedades juntas cria um iterável rápido para percorrer a árvore do bundle.

Um exemplo muito básico de uma árvore de asset e gerando uma árvore de bundle.

Árvore de assets:

index.html requer index.js e index.css.

index.js requer test.js e test.txt

index.html
-- index.js
 |--- test.js
 |--- test.txt
-- index.css
Bundle Tree

index.html é utilizado como um asset de entrada para o bundle principal, este bundle principal cria dois bundles filhos, um para index.js e um para index.css, isto porque ambos são diferentes do tipo html.

index.js requer dois arquivos, test.js e test.txt.

test.js será adicionado aos assets do bundle index.js, e iste será do mesmo tipo que index.js

test.txt cria um novo bundle e será adicionado como filho do bundle index.js como sendo de um assetType diferente de index.js

index.css não tem requerimento e portanto só contém seu Asset de entrada.

Os bundles index.css e index.js são bundles irmãos um do outro e eles compartilham do mesmo pai.

index.html
-- index.js (inclui index.js e test.js)
 |--- test.txt (inclui test.txt)
-- index.css (inclui index.css)

Middleware

Middleware pode ser utilizado como hoot dentro do servidor http (por exemplo, express ou http Node)

Um exemplo de uso de middleware do Parcel com o express:

const Bundler = require('parcel-bundler');
const app = require('express')();

const file = 'index.html'; // Passa um caminho absoluto para o entrypoint aqui
const options = {}; // Veja a sessão se opções da documentação da API, para as possibilidades.

 // Inicializa o bundler utilizando a localização do entrypoint e as configurações especificadas.
const bundler = new Bundler(file, options);

// Deixa o express usar o middleware do bundle, isto deixará o Parcel controlar cada requisição feita ao servidor do express
app.use(bundler.middleware());

// Escutando a porta 8080
app.listen(8080);

Ajude-nos a melhorar esta documentação

Se alguma coisa estiver faltando ou não estiver inteiramente clara, por favor crie uma issue no repositório deste site ou edite esta página.